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Introduction 


SECTION  1 
Introduction 


The  Sail  manual  [1]  is  a reference  manual 
containing  complete  information  on  Sail  but  may 
be  difficult  for  a new  user  of  the  language  to 

work  with.  The  purpose  of  this  TUTORIAL  * is  to 
introduce  new  users  to  the  language.  It  does  not 
deal  in  depth  with  advanced  features  like  the 
LEAP  portion  of  Sail;  and  uses  pointers  to  the 
relevant  portions  of  the  manual  for  some 
descriptions.  aFollowing  the  pointers  and  reading 
specific  portions  of  the  manual  will  help  you  to 
develop  some  familiarity  with  the  manual.  After 
you  have  gained  some  Sail  programming 
experience,  it  will  be  worthwhile  to  browse 
through  the  complete  reference  manual  to  find  a 
variety  of  more  advanced  structures  which  are 
not  covered  in  the  TUTORIAL  but  may  be  useful 
in  your  particular  programming  tasks.  The  Sail 
manual  also  covers  use  of  the  BAIL  debugger  for 
Sail. 

The  TUTORIAL  is  not  at  ar.  appropriate  level  for 
a computer  novice.  The  following  assumptions 
are  made  about  the  background  of  the  reader: 

1 ) Some  experience  with  the  PDP- 
10  including  knowledge  of  an  editor, 
understanding  of  the  file  system,  and 
familiarity  with  routine  utility  programs 
and  system  commands.  If  you  are  a new 
user  or  have  previous  experience  only 
on  a non-timesharing  system,  you  should 
read  the  TENEX  EXEC  MANUAL  [7]  (for 
TENEX  systems)  or  the  DEC  USERS 
HANDBOOK  [6]  (for  standard  TOPS-10 
systems)  or  the  MONITOR  MANUAL  [3] 
and  UUO  MANUAL  [2]  (for  Stanford  Al 
Lab  users).  In  addition,  you  might  want 
to  glance  through  and  keep  ready  for 
reference:  the  TENEX  JSYS  MANUAL  [8] 
and/or  the  DEC  ASSEMBLY  LANGUAGE 
HANDBOOK  [5].  Also,  each  PDP-10 
system  usually  has  its  own  introductory 
material  (or  rww  users  describing  the 
operation  of  the  system. 

2)  Some  experience  with  a 

programming  language--probably 

FORTRAN,  ALG(X  or  an  assembly 


language.  If  you  have  no  programming 
experience,  you  may  need  help  getting 
started  even  with  this  TUTORIAL.  Sail  is 
based  on  ALGOL  so  the  general  concepts 
and  most  of  the  actual  statements  are  the 
same  in  what  is  often  called  the  'ALGOL 
part"  of  Sail.  The  major  additions  to  Sail 
are  its  input/output  routines.  Appendix 
A contains  a list  of  the  differences 
between  the  ALCjOL  W syntax  and  Sail. 

Programs  written  in  standard  Sail  (which  will 
henceforth  be  called  TOPS'lO  Sail)  will  usually 
run  on  a TENEX  system  through  the  emulator 
(PA1050)  which  simulates  the  TOPS-10  UUO’s, 
but  such  use  is  quite  inefficient.  Sail  also  has  a 
version  for  TENEX  systems  which  we  refer  to  as 
TENEX  Sail.  (The  new  TOPS-20  system  is  very 
similar  to  TENEX;  either  TENEX  Sail  or  a new  Sail 
version  should  be  running  on  TOPS-20  shortly.) 
Note  that  the  Sail  compiler  on  your  system  will 
be  called  simply  Sail  but  will  in  fact  be  either  the 
TENEX  Sail  or  TOPS-10  Sail  version  of  the 
compiler.  Aside  from  implementation  differences 
which  will  not  be  discussed  here,  the  language 
differeiKes  are  mainly  in  the  input /output  (I/O) 
routines.  And  of  course  the  system  level 
commands  to  compile,  load,  and  run  a finished 
program  differ  slightly  in  the  TENEX  and  TOPS- 
10  systems. 


* I would  like  to  thank  Robert  Smith  for  editing 
the  final  version;  and  Scott  Daniels  for  his 
contributions  to  the  RECORD  section.  John 
Reiser,  Les  Earnest,  Russ  Taylor,  Marney  Beard, 
and  Mike  Hinckley  all  made  valuable  suggestions. 
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SECTION  2 

The  ALGa-Part  of  Sail 


2.1  Blocks 

Sail  is  a blocK-airucturad  language.  Each  block 
has  the  form: 

BEGIN 

<d*c larat lont> 


<stat*a*nti> 


END 

Your  entire  program  will  be  a block  with  the 
above  format.  This  program  block  is  a somewhat 
special  block  called  the  outer  block.  BEGIN  and 
END  are  reserved  words  in  Sail  that  mark  the 
beginning  and  end  of  blocks,  with  the  outermost 
BEGIN/ENO  pair  also  marking  the  beginning  and 
end  of  your  program.  (Reserved  words  are 
words  that  automatically  mean  something  to  Sail; 
they  are  called  'reserved'  because  you  should 
not  try  to  give  them  your  own  meaning.) 

Decleratiene  are  used  to  give  the  compiler 
information  about  the  data  structures  that  you 
will  be  using  so  that  the  compilar  can  sat  up 
storage  locations  of  the  proper  types  and 
associate  the  desired  name  with  each  location. 

Statements  form  the  bulk  of  your  program.  They 
are  the  ectual  commands  available  in  Sail  to  use 
for  coding  the  task  at  hand. 

All  declarations  in  each  block  must  precade  all 
etstements  in  that  block.  Here  is  a very  simple 
one-block  program  that  outputs  the  square  root 
of  5: 

BEGIN 

OCCLaKNTIONS  >■>  INTCGCk  l| 

MIN.  i| 

STaTCNCNTf  ■■>  t . t| 

« > SONTItli 

PNINTt'SQUItM  ROOT  OF  *,  I, 

• I«  *,  «»l 
END 


which  will  print  out  on  the  terminal: 
SQUARE  ROOT  OF  S IS  2.236B68 


2.2  Declarations 

A list  of  all  the  kinds  of  declarations  is  given  in 
the  Sail  manual  (Sec.  2.1).  In  this  section  we  will 
cover  type  declarations  and  array  declarations. 
Procedure  declarations  will  be  discussed  in 
Section  2.7.  Consult  the  Sail  manual  for 
details  on  all  of  the  other  varieties  of 
declarations  listed. 

2.2.1  Type  Declarations 

The  purpose  of  type  declarations  is  to  tell  the 
compiler  what  it  needs  to  know  to  set  up  the 
storage  locations  for  your  data.  There  are  four 
data  types  available  in  the  AUSOL  portion  of  Sail: 

1)  INTEGERS  are  counting  numbers 
like  -1,  0,  1,  2,  3,  etc.  (Note  that  commas 
cannot  be  used  in  numbers,  e.g.,  15724 
not  15,724.) 

2)  REALS  are  decimal  numbers  like 
-1.2,  3.14159,  100087.2,  etc. 

3)  BOOLEANs  are  assigned  the 
values  TRUE  or  FALSE  (which  are 
reserved  words).  These  are  predefined 
for  you  in  Sail  (TRUE  - -1  and  FALSE  • 

0). 

4)  STRINGS  are  a data  type  not 
found  in  all  programming  languages. 
Very  often  what  you  will  be  working  with 
are  not  numbers  at  all  but  text.  Your 
program  may  need  to  output  text  to  the 
user’s  terminal  while  he/she  is  running 
the  program.  It  may  ask  the  user 
questions  and  input  text  which  is  the 
answer  to  the  question.  It  may  in  fact 
process  whole  files  of  text.  One  simple 
example  of  this  is  a program  which  works 
with  a file  containing  a list  of  words  and 
outputs  to  a new  file  the  same  list  of 
words  in  alphabetical  order.  It  is 
possible  to  do  these  things  in  languages 
with  only  the  integer  and  real  data  types 
but  very  clumsy.  Text  has  certain 
properties  different  from  those  of 
numbers.  For  example,  it  is  very  useful 
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\qi'  be  able  to  point  fo  certain  of  the 
^'characters  in  the  text  and  work  with  just 
y those  temporarily  or  to  take  one  letter 
off  of  the  text  at  a time  and  process  it. 
Sail  has  the  data  type  STRING  for  holding 
"strings"  of  text  characters.  And 
associated  with  the  STRING  data  type  are 
string  operations  that  work  in  a way 
analogous  to  how  the  numeric  operators 
etc.)  work  with  the  numeric  data 
types.  We  write  the  actual  strings 
enclosed  in  quotation  marks.  Any  of  the 
characters  in  the  ASCII  character  set  can 
be  used  in  strings  (control  characters, 
letters,  numerals,  purKtuation  marks). 
Some  examples  of  strings  are: 

■OUTPUT  file.  ■ 

•HELP- 

-Plaaia  typa  your  naaa.* 

■••rduark ■ 

■ai234567a9* 

•'■■#$7«" 

-AaBbCcOdEtFr 

"■  (lh»  CRply  tlrlny) 

NULL  (alto  lha  tapty  tinny) 

Upper  and  lowercase  letters  are  not 
equivalent  in  strings,  i.e.,  "a"  is  a 
different  string  than  "A".  (Note  that  to 
put  a " in  a string,  you  use  "",  e g.,  "quote 
a ""word""".) 

In  your  programs,  you  will  have  both  variables 
and  constants.  We  have  already  given  some 
examples  of  constants  in  each  of  the  data  types. 
REAL  and  INTEGER  constants  are  just  numbers  as 
you  usually  see  them  written  (2,  618,  -4.35,  etc.); 
the  BOOLEAN  constants  are  TRUE  and  FALSE;  and 
STRING  constants  are  a sequerKe  of  text 
characters  enclosed  in  double  quotes  (and  NULL 
for  the  empty  string). 

Variables  are  used  rather  than  constants  when 
you  know  that  a value  will  be  needed  in  the 
given  computation  but  do  not  know  in  advance 
what  the  exact  value  will  be.  For  example,  you 
may  want  to  add  4 numbers,  but  the  numbers 
will  be  specified  by  the  user  at  runtime  or  taken 
from  a data  file.  Or  the  numbers  may  be  the 
results  of  previous  computations.  You  might  be 
computing  weekly  totals  and  then  when  you  have 
the  results  for  each  week  adding  the  four  weeks 
together  for  a monthly  total.  So  instead  of  an 
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expression  like  2 + 31  +25  + 5 you  need  an 
expression  like  X + Y + Z + W or 

WEEKl  ♦ WEEK2  + WEEKS  + WEEK4.  This  is  done 
by  declaring  (through  a declaration)  that  you  will 
need  a variable  of  a certain  data  type  with  a 
specified  name.  The  compiler  will  set  up  a 
storage  location  of  the  proper  type  and  enter 
the  name  and  location  in  its  symbol  table.  Each 
time  that  you  have  an  intermediate  result  which 
needs  to  be  stored,  you  must  set  up  the  storage 
location  in  advance.  When  we  discuss  the 
various  statements  available,  you  will  see  how 
values  are  input  from  the  user  or  from  a file  or 
saved  from  a computation  and  stored  in  the 
appropriate  location.  The  names  for  these 
variables  are  often  referred  to  as  their 
identifiers.  Identifiers  can  be  as  long  (or  short) 
as  you  want.  However,  if  you  will  be  debugging 
with  DDT  or  using  TOPS-10  programs  such  as 
the  CREF  cross-referencing  program,  you  should 
make  your  identifiers  unique  to  the  first  six 
characters,  i.e.,  DDT  can  distinguish  LONGSYMBOL 
from  LONGNAME  but  not  from  LONGSYNONYM 
because  the  first  6 characters  are  the  same. 
Identifiers  must  begin  with  a letter  but  following 
that  can  be  made  up  of  any  sequence  of  letters 
and  numbers.  The  characters  ! and  S are 
considered  to  be  letters.  Certain  reserved  words 
and  predeclared  identifiers  are  unavailable  for 
use  as  names  of  your  own  identifiers.  A list  of 
these  is  given  in  the  Sail  manual  in  Appendices  B 
and  C. 

Typical  declarations  are: 

INTEGER  l,t,X| 

REAL  x,y,Z| 

STRING  i,t| 

where  these  are  the  letters  conventionally  used 
as  identifiers  of  the  various  types.  There  is  no 
reason  why  you  couldn't  have  integer  xi  real  i| 
except  that  other  people  reading  your  program 
might  be  confused.  In  some  languages  the  letter 
used  for  the  variable  automatically  tells  its  type. 
This  is  not  true  in  Sail.  The  type  of  the  variable 
is  established  by  the  declaration.  In  general, 
simple  one-letter  identifiers  like  these  are  used 
for  simple,  straightforward  and  usually 
temporary  purposes  such  as  to  count  an 
iteration.  (ALGOL  W users  note  that  iteration 
variables  must  be  declared  in  Sail.) 

Most  of  the  variables  in  your  program  will  be 
declared  and  used  for  a specific  purpose  and  the 
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name  you  specify  should  reflect  the  use  of  the 
variable. 

INTECtR  ntxtUord,  pAgt^count; 

REPL  totAl,  subTotPl; 

STRING  firitnPM) 

BOOlEPN  partial,  abortSmtch,  oulpultM; 

Both  upper  and  lowercase  letters  are  equivalent 
in  identifiers  and  so  the  case  as  well  as  the  use 
of  ! and  8 can  contribute  to  the  readability  of 
your  programs.  Of  course,  the  above  examples 
contain  a mixture  of  styles;  you  will  want  to 
choose  some  style  that  looks  best  to  you  and 
use  it  consistently.  The  equivalence  of  upper 
and  lowercase  also  means  that 

TOTRL  I total  I Total  | toTal  | ate. 

are  all  instances  of  the  same  identifier.  So  that 
while  it  IS  desirable  to  be  consistent,  forgetting 
occasionally  doesn’t  hurt  anything. 

Some  programmers  use  uppercase  for  the 
standard  words  like  BEGIN,  INTEGER,  END,  etc. 
and  lowercase  for  their  identifiers.  Others 
reverse  this.  Another  approach  is  uppercase  for 
actual  program  code  and  lowercase  for 
comments.  It  is  important  to  develop  some  style 
which  you  feel  makes  your  programs  as  easy  to 
read  as  possible. 

Another  important  element  of  program  clarity  is 
the  format.  The  Sail  compiler  is  free  formal 
which  means  that  blank  lines,  indentations,  extra 
spaces,  etc.  are  ignored.  Your  whole  program 
could  be  on  one  line  and  the  compiler  wouldn't 
know  the  difference.  (Lines  should  be  less  than 
250  characters  if  a listing  is  being  made  using 
the  compiler  listing  options.)  But  programs 
usually  have  each  statement  and  declaration  on  a 
separate  line  with  all  lines  of  each  block 
indented  the  same  number  of  spaces.  Some 
programmers  put  BEGIN  and  END  on  lines  by 
themselves  and  others  put  them  on  the  closest 
line  of  code.  It  is  very  important  to  format  your 
programs  so  that  they  are  easy  to  read. 


2.2.2  Array  Declarations 

An  array  is  a data  structure  designed  to  let  you 
deal  with  a group  of  variables  together.  For 
example,  if  you  were  accumulating  weekly  totals 
over  a period  of  a year,  it  would  be  cumbersome 
to  declare: 

RERL  HtaKl,  H*«k2,  H««k3, ,H«*kS2  ; 

and  then  have  to  work  with  the  52  variables 
each  having  a separate  name.  Instead  you  can 
declare: 

RERL  RRRRV  uatki  [1;S2)  i 

The  array  declaration  consists  of  one  of  the  data 
type  words  (REAL,  INTEGER,  BOOLEAN,  STRING) 
followed  by  tne  word  ARRAY  followed  by  the 
identifier  followed  by  the  dimensions  of  the 
array  enclosed  in  [ ]’s.  The  dimensions  give  the 
bounds  of  the  array.  The  lower  bound  does  not 
need  to  be  1.  Another  common  value  for  the 
lower  bound  is  0,  but  you  may  make  it  anything 
you  like.  (The  LOADER  will  have  difficulties  if  the 
lower  bound  is  a number  of  large  positive  or 
negative  magnitude.)  You  may  declare  more  than 
one  array  in  the  same  declaration  provided  they 
are  the  same  type  and  have  the  same 
dimensions.  For  example,  one  array  might  be 
used  for  the  total  employee  salary  paid  in  the 
week  which  will  be  a real  number,  but  you  might 
also  need  to  record  the  total  employee  hours 
worked  and  the  total  profit  made  (one  integer 
and  one  real  value)  so  you  could  declare: 

INTEGER  RRRRY  hours  U:S2)| 

RERL  RRRRV  ttlsrist,  profits  [liS2I| 

These  3 arrays  are  examples  of  parallel  arrayt. 

It  is  also  possible  to  have  multi-dimensiorred 
arrays.  A common  example  is  an  array  used  to 
represent  a chessboard: 


INTEGER  RRRRV  chossboord  tli8,l:S)| 


1.1 

1.2 

1,3 

1.8 

i.s 

1,8 

1.2 

1.8 

2.1 

2,2 

2,3 

2,* 

2.5 

2,6 

2,2 

2,8 

*.l 

8.2 

8,3 

8,8 

ais 

8,6 

8^2 

8,8 
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In  fact  even  the  terminology  used  is  the  same. 
Arrays,  like  matrices  and  chessboards,  have  rows 
(across)  and  columns  (up-and-down).  Arrays 
which  are  statically  allocated  (all  outer  block  and 
OWN  arrays)  may  have  at  most  5 dimensions. 
Arrays  which  are  allocated  dynamically  may  have 
any  number  of  dimensions. 

Each  element  of  the  array  is  a separate  variable 
and  can  be  used  anywhere  that  a simple  variable 
can  be  used.  We  refer  to  the  elements  by  giving 
the  name  of  the  array  followed  by  the  particular 
coordinates  (called  the  tubteriptc)  of  the  given 
element  enclosed  in  []’s,  for  example:  uttti[34), 
w««ktI271,  ck«(tboardl2,S1 , and  ckattboard[(,8). 


2.3  Statements 

All  of  the  statements  available  in  Sail  are  listed 
in  the  Sail  manual  (Sec.  1.1  with  the  syntax  for 
the  statements  in  Sec.  3.1).  For  now,  we  will 
discuss  the  assignment  statement,  the  PRINT 
statement,  and  the  IF. ..THEN  statement  which  will 
allow  us  to  give  some  sample  programs. 

2.3.1  Assignment  Statement 

Assignment  statements  are  used  to  assign  values 
to  variables: 

varlabla  •Kpraiiion 

The  variable  being  assigned  to  and  the 
expression  whose  value  is  being  assigned  to  it 
are  separated  by  the  character  which  is  a 
backwards  arrow  in  1965  ASCII  (and  Stanford 
ASCII)  and  is  an  underbar  (underlining  character) 
in  1968  ASCII.  The  assignment  statement  is 
often  read  as: 

var lab  lb  bacomat  axpratalan 
OR  variabla  la  aan9nad  tba  valua  of  aipraaalon 
OR  variabla  qatt  axpraatlon 

You  may  assign  values  to  any  of  the  four  types 
of  variables  (INTEGER,  REAL,  BOOLEAN,  STRING) 
or  to  the  individual  variables  in  arrays. 

Essentially,  an  expression  is  something  that  has  a 
value.  An  expression  is  not  a statement 
(although  we  will  see  later  that  some  of  the 
constructions  of  the  language  can  be  either 
statements  or  expressions  depending  on  the 
current  use).  It  is  most  important  to  remember 


that  an  expression  can  be  evaluated.  It  is  a 
symbol  or  sequence  of  symbols  that  when 
evaluated  produces  a value  that  can  be  assigned, 
used  in  a computation,  tested  (eg.  for  equality 
with  another  value),  etc.  An  expression  may  be 

a)  a constant 

b)  a variable 

c)  a construction  using  constants, 
variables,  and  the  various  operators  on 
them. 


Examples  of  these  3 types  of  expressions  in 
assignment  statements  are: 


DON’T  FORGET  TO  OECLRRE  VRRIRBLES  FIRST  I 


INTEGER  i,j( 
real  «,q; 

STRING  I,1| 

BOOLEAN  iXM,otu, lotu; 
INTEGER  ARRAY  arrq  11:10) j 


a) 


i «■  2) 

X 2.4{ 

I "abe'i 
liH  > TRUE  I 
0(u  • FALSE; 
arryU)  ••  22| 


COkNEHT  now  i « 2 j 
COHRENT  now  x ■ 2.4; 
COnriENT  nou  EQU(»,"abc")i 
COnnENT  nou  isM  . TRUE; 
CONflENT  nou  oxu  ■ FALSE; 
COIIflENT  nou  arryI4)  • 22; 


b)  J ► I; 
y * x; 

• ‘ »l 

arrylB)  - j; 


COnnENT  nou  I • j • 2; 
COfIRENT  nou  x ■ y « 2.4; 
CORRENT  nou  EQU(i, "abc") 
AND  EOUd.'-abc''); 
CORRENT  i.j.arryI8).2; 


e)  I •.  J t 4;  CORRENT  j • 2 AND  i • 6; 

X - 2y  - I;  CORRENT  y«2.4  AND  I >6 

AND  X • -1.2; 

arryO)  - l/j;  CORRENT  1.6  AND  J.2 

AND  arryI3l.3; 

lolu  . iiu  OR  0(u;  CORRENT  Itu  • TRUE 
RNO  oiu  • FALSE 
AND  iocu  . TRUE; 


NOTEl:  Most  of  the  operators  for  strings 
are  different  than  those  for  the 
arithmetic  variables.  The  difference 
between  ■ and  EQU  will  be  covered 
later. 


N0TE2:  Logical  operators  such  as  AND 
and  OR  are  also  available  for 
boolean  expressions. 
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NOTE3:  You  may  put  "comments" 
anywhere  in  your  program  by  using 
the  word  COMMENT  followed  by  the 
text  of  your  comment  and  ended 
with  a semi-colon  (no  semi-colons 
can  appear  within  the  comment). 
Generally  comments  are  placed 
between  declarations  or  statements 
rather  than  inside  of  them. 

IMOTE4:  In  all  our  examples,  you  will  see 
that  the  declarations  and  statements 
are  separated  by  semi-colons. 

In  a later  section,  we  will  discuss:  1)  type 
conversion  which  occurs  when  the  data  types  of 
the  variable  and  the  expression  are  not  the 
same,  2)  the  Order  of  evaluation  in  the 
expression,  and  3)  many  more  complicated 
expressions  including  string  expressions  (first  we 
need  to  know  more  of  the  string  operators). 


2.3.2  PRINT  Statement 

PRINT  is  a relatively  new  but  very  useful 
statement  in  Sail.  It  is  used  for  outputting  to  the 
user’s  terminal.  You  can  give  it  as  many 
arguments  as  you  want  and  the  arguments  may 
be  of  any  type.  PRINT  first  converts  each 
argument  to  a string  if  necessary  and  then 
outputs  it.  Remember  that  only  strings  can  be 
printed  anywhere.  Numbers  are  stored 
internally  as  36-bit  words  and  when  they  are 
output  in  7-bit  bytes  for  text  the  results  are 
very  strange.  Fortunately  PRINT  does  the 
conversion  to  strings  for  you  automatically,  e.g., 
the  number  237  is  printed  as  the  string  "237". 
The  format  of  the  PRINT  statement  is  the  word 
PRINT  followed  by  a list  of  arguments  separated 
by  commas  with  the  entire  list  enclosed  in 
parentheses.  Each  argument  may  be  any 
constant,  variable,  or  complex  expression.  For 
example,  if  you  wanted  to  output  the  weekly 
salary  totals  from  a previous  example  and  the 
number  of  the  current  week  was  stored  in 
INTEGER  curUtat,  you  might  use: 

FRINTCUEEK  *,  curUtaX, 

"i  Salarlaa  *,  aalar laateurUaaX] ) | 

which  for  curUaak  • 2S  and  the  array  element 
aalarlaalZS)  • 27S43.S2  would  print  uut: 

UEEK  2«i  Salarlaa  27S43.»2 
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NOTE:  The  printing  format  for  reals 
(number  of  leading  zeroes  printed 
and  places  after  the  decimal  point) 
is  discussed  in  the  Sail  manual  under 
type  conversions. 


2.3.3  Built-in  Procedures 

Using  just  the  assignment  statement,  the  PRINT 
statement,  and  three  built-in  procedures,  we  can 
write  a sample  program.  Procedures  are  a very 
important  feature  of  Sail  and  you  will  be  writing 
many  of  your  own.  The  details  of  procedure 
writing  and  use  will  be  covered  in  Section 
2.7.  Without  giving  any  details  now,  we  will 
just  say  that  some  procedures  to  handle  very 
common  tasks  have  been  written  for  you  and  are 
available  as  built-in  procedures.  The  SORT, 
INCHWL  and  CVD  procedures  that  we  will  be 
using  here  are  all  procedures  which  return 
values.  Examples  are; 

• - INCHULi 
I - CVD(t)j 
X •.  2 * SORTCD) 

Procedures  may  have  any  number  of  arguments 
(or  none).  SQRT  and  CVS  have  a single  argument 
and  INCHWL  has  no  arguments  (but  does  return  a 
value).  The  procedure  call  is  made  by  writing 
the  procedure  name  followed  by  the  argument(s) 
in  parentheses.  In  the  expression  in  which  it  is 
used,  the  procedure  call  is  equivalent  to  the 
value  that  li  returns. 

SQRT  returns  the  square  root  of  its 
argument. 

CVD  returns  the  result  of  converting  its 
string  argument  to  an  integer.  The 
string  is  assumed  to  contain  a 
number  in  decimal  representation-- 
CVO  converts  strings  containing 
octal  numbers,  e.g.,  after  executing 

I - CV0C14724-)|  I ► CV0C14724")| 
then  the  following 
I . 14724  RNO  i • 6612 

would  be  true. 

INCHWL  returns  the  next  line  of  typing 
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from  the  user  at  the  cor>troUir\g 
terminal. 

NOTE:  In  TENEX-Sail  the  INTTY  procedure 
IS  available  and  SHOULD  be  used  in 
preference  to  the  INCHWL  procedure 
for  inputting  lines.  This  may  not  be 
mentioned  in  every  example,  but  is 
very  important  for  TENEX  users  to 
remember. 

So,  for  the  statement  ■ INCHULi  , the  value  of 
INCHWL  will  be  the  line  typed  at  the  terminal 
(minus  the  terminator  which  Is  usually  carriage 
return).  This  value  is  a string  and  is  assigned 
here  to  the  string  variable  *. 

So  far  we  have  seen  five  uses  of  expressions;  as 
the  right-hand-side  of  the  assignment  statement, 
as  an  actual  parameter  or  argument  in  a 
procedure  call,  as  an  argument  to  the  PRINT 
statement,  for  giving  the  bounds  in  an  array 
declaration  (except  for  arrays  declared  in  the 
outer  block  which  must  have  constant  bounds), 
and  for  the  array  subscripts  for  the  elements  of 
arrays.  In  fact  the  whole  range  of  kinds  of 
expressions  can  be  used  in  nearly  all  the  places 
that  constants  and  variables  (which  are 
particular  kinds  of  expressions)  can  be  used. 
Two  exceptions  to  this  that  we  have  already 
seen  are  1)  the  left-hand-side  of  the  assignment 
statement  (you  can  assign  a value  to  a variable 
but  not  to  a constant  or  a more  complicated 
expression)  and  2)  the  array  bounds  for  outer 
block  arrays  which  come  at  a point  in  the 
program  before  any  assignments  have  been 
made  to  any  of  the  variables  so  only  constants 
may  be  used--the  declarations  in  the  outer  block 
are  before  any  program  statements  at  all. 

In  general,  any  construction  that  makes  sense  to 
you  is  probably  legal  in  Sail.  By  using  some  of 
the  more  complicated  expressions,  you  can  save 
yourself  steps  in  your  program.  For  example, 

BEGIN 

RERL  tqrooli 
INTEGER  nu>il)| 

STRING  raplyi 
PRINT(“Typ#  nu«b«rt  ")| 
r«ply>]NCHUL; 
f>umbe>CVD  (r«p  ly)  i 
•qroot*-50RT (nu«b)  | 

PRINT(*ANSi  ”,iqroo1)| 

CND| 

can  be  shortened  by  several  steps.  First,  we 
can  combine  inchm.  with  evD: 


numb  - eVD  (INCHUL)| 

and  eliminate  the  declaration  of  the  string  r»piy. 
Next  we  can  eliminate  numb  and  take  the  SORT 
directly: 

tqroot  - SORT  (CVDdNCHUL)); 

At  first  you  might  think  that  we  could  go  a step 
further  to 

PRINT  ("HNSi  ".SORTfCVOUNCHUUn  ; 

and  we  could  as  far  as  the  Sail  syntax  is 
concerned  but  it  would  produce  a bug  in  our 
program.  We  would  be  printing  out  "RNS:  " right 
after  "Typ#  numbtn  " before  the  user  would  have 
time  to  even  start  typing.  But  we  have 
considerably  simplified  our  program  to: 

BEGIN 

REAL  tqroot; 

PRINT  ("Typq  numbR^i  ")j 
tqroot  r SORT  (CVD ( INCHUL I ) | 

PRINT  ("RNSi  ", tqroot); 

END; 

Remember  that  intermediate  results  do  not  need 
to  be  stored  unless  you  will  need  them  again 
later  for  something  else.  By  not  storing  results 
unnecessarily,  you  save  the  extra  assignment 
statement  and  the  storage  space  by  not  needing 
to  declare  a variable  for  temporary  storage. 


2.3.4  IF...THEN  Statement 

The  previous  example  included  no  error 
checking.  There  are  several  fundamental 
programming  tasks  that  cannot  be  handled  with 
just  the  assignment  and  PRINT  statements  such 
as  1)  conditional  tasks  like  checking  the  value  of 
a number  (is  it  negative?)  and  taking  action 
according  to  the  result  of  the  test  and  2)  looping 
or  iterative  tasks  so  that  we  could  go  back  to 
the  beginning  and  ask  the  user  for  another 
number  to  be  processed.  These  sorts  of 
functions  are  performed  by  a group  of 
statements  called  control  statements.  In  this 
section  we  will  cover  the  IF..THEN  statement  for 
conditionals.  More  advanced  control  statements 
will  be  discussed  in  Section  2.6. 

There  are  two  kinds  of  IF...THEN  statements: 

IF  bool««n  •Kprcition  THEN  ttattiRqnt 
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ir  boolean  •xpr«sKion  THEN 

ELSE  »tat«m«nl 

A boolean  expression  is  an  expression  whose 
value  IS  either  true  or  false.  A wide  variety  of 
expressions  can  effectively  be  used  in  this 
position.  Any  arithmetic  expression  can  be  a 
boolean;  if  its  value  • 0 then  it  is  fblse.  For  any 
other  value,  it  is  true.  For  now  we  will  just 
consider  the  following  three  cases; 

1)  BOOLEAN  variables  (where 
•rroriu,  b<t«8,  and  Min  I V«rt  lon  are 
declared  as  BOOLEANs): 

IF  errorsw  THEN 

PRINT ("Th«r«*i  bb«n  #n  tpror.")  ; 

IF  baseS  then  digitt  •-  '(  ’34S67' 

ELSE  digits  ► i)123*5G7«9“  ) 

IF  miniVersion  then  counisr  ► le 

ELSE  coun\«r  *■  108; 

2)  Expressions  with  relational 
operators  such  as  EQU,  <,  >,  LEQ, 

NEO,  and  GEQ; 

IF  X < currentSmallest  THEN 

curr«ntSMn«tt  ••  m| 

IF  divisor  NEO  0 then 

quot  l•nt•’dlvld•nd/dlv(ior) 

IF  i GEQ  0 then  ui«i  else  l•^l-l| 


COrWENT  i.3  SND  j-2; 

END) 

It  IS  VERY  IMPORTANT  to  note  that  NO  semi-colon 
appears  between  the  statement  and  the  ELSE. 
Semi-colons  are  used  a)  to  separate  declarations 
from  each  other,  b)  to  separate  the  final 
declaration  from  the  first  statement  in  the  block, 

c)  to  separate  statements  from  each  other,  and 

d)  to  mark  the  end  of  a comment.  The  key  point 
to  note  IS  that  semi-colons  are  used  to  separate 
and  NOT  to  terminate.  In  some  cases  it  doesn’t 
hurt  to  put  a semi-colon  where  it  is  not  needed. 
For  example,  no  semi-colon  is  needed  at  the  end 
of  the  program  but  it  doesn’t  hurt.  However,  tr.e 
format 

IF  •xprtftion  THEN  ; ELSE  statement  ; 

makes  it  difficult  for  the  compiler  to  understand 
your  code.  The  first  semi-colon  marks  the  end 
of  what  could  be  a legitimate  IF...THEN  statement 
and  it  will  be  taken  as  such.  Then  the  compiler 
IS  faced  with 

ELSE  statimnt  ; 

which  is  meaningless  and  will  produce  an  error 
message. 

The  following  is  a part  of  a sample  program 
which  uses  several  IF...THEN  statements: 

BEGIN  BOOLEAN  vtrbotttM;  STRING  rtplg; 


3)  Complex  expressions  formed 
with  the  logical  operators  AND,  OR,  and 
NOT: 

IF  NOT  errorsw  THEN 

ansMtrs  tcountar]  •-  quotient; 

IF  X<0  OR  y<0  THEN 

PRINT(*N«gb1 iva  nuMbtrs  not  bllouod.*! 
ELSE  I . SQRT(»)«SORT(g), 


PRINTCVorbosa  Mod«7  (Tgpo  Y or  N):  "I; 
ropig  » INCHUL;  COfinENT  INTTY  (or  TENEX; 

IF  r#plg«"Y"  OR  r#ply«"g*  THEN  vorbososw  •-  TRUE 
ELSE 

IF  roply«"N"  OR  roplg«“n"  THEN  vorbososM-FBLSE ; 


In  the  IF.  THEN  statement,  the  boolean  expression 
IS  evaluated.  If  if  is  true  then  the  statement 
following  the  THEN  is  executed.  If  the  boolean 
expression  is  false  and  the  particular  statement 
has  no  ELSE  part  then  nothing  is  done.  If  the 
boolean  is  false  and  there  is  an  ELSE  part  then 
the  statement  following  the  ELSE  will  be 
executed. 


BEGIN  BOOLEAN  bool;  INTEGER  l,ti 
booIrTRUE;  Irl;  J*-l| 

IF  bool  then  IrUl)  COnnENT  1.2  AND  J.l) 
IF  bool  THEN  UUl  ELSE  i-J«l| 

COnnENT  1.3  and  J.l) 


bool. la  I so  I 

IF  bool  THEN  |.U1|  COnnENT  1.3  AND  j.l) 
IF  bool  THEN  l.l.l  ELSE  J.J.li 


IF  vorbososw  THEN  PRINTC-long  Msg-') 

ELSE  PRINTC-short  Msg-"); 

COnnENT  now  oil  our  Mossogos  pnntod  out  to 
tornlnol  will  bo  conditional  on  vorbososw; 

END; 

There  are  two  interesting  points  to  note  about 
this  sample  program.  First  is  the  use  of  - rather 
than  EQU  to  check  the  user’s  reply.  EQU  is  used 
to  check  the  equality  of  variables  of  type  STRING 
and  - IS  used  to  check  the  equality  of  variables 
of  type  INTEGER  or  REAL.  If  we  were  asking  the 
user  for  a full  word  answer  like  "yes"  or  "no" 
instead  of  the  single  character  then  we  would 
need  the  EQU  to  check  what  the  input  string  was. 
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However,  m this  case  where  we  only  have  a 
single  characler,  we  can  use  the  fact  that  when  a 
string  (either  a string  variable  Or  a string 
constant)  is  put  someplace  in  a program  where 
an  integer  is  expected  then  Sail  automatically 
converts  to  the  integer  which  is  the  ASCII  code 
for  the  FIRST  character  in  the  string.  For 
example,  in  the  environment 

STRING  ilr;  sir  ••  *R"( 

all  of  the  following  are  true: 

. Hr  . BS  • '1(1 
■R-  NEQ 
Sir  NEQ 

■Ir  ♦ 1 ■ "R"  ♦ 1 • ' lf2  ■ "B" 

t!r  ■ "R«rdv«rk" 

NOT  EQU (» tr , "Rardvark " ) 

riOl  IS  an  Octal  integer  constant.) 

When  you  are  dealing  with  single  character 
strings  (or  are  only  interested  in  the  first 
character  of  a string)  then  you  can  treat  them 
like  integers  and  use  the  arithmetic  operators 
like  the  - operator  rather  than  EQU.  In  general 
(over  SOX  of  the  time),  EQU  is  slower. 

A second  point  to  note  in  the  above  IF...THEN 
example  is  the  use  of  a rtesfed  IF...THEN.  The 
statements  following  the  THEN  and  the  ELSE  may 
be  any  kind  of  statement  including  another 
IF..THEN  statement.  For  example, 

IF  upparOnly  THEN  laltari  » "RBC" 

ELSE  IF  lowarOniy  THEN  lattarg  *•  *abc* 

ELSE  1*1  lari  •.  ’RBCabc'i 

This  is  a very  common  construction  when  you 
have  a small  list  of  possibilities  to  check  for. 
(Note:  if  there  are  a large  number  of  cases  to  be 
checked  use  the  CASE  statement  instead.)  The 
nested  IF. .THEN.. ELSE  statements  save  a lot  of 
processing  if  used  properly.  For  example, 

without  the  nesting  this  would  be: 

IF  upparOnly  THEN  lallart  ► “BBC'j 
IF  loHtrOnly  THEN  lalttri  *abc*| 

IF  NOT  upparOnly  RND  NOT  lOHtrOnly  THEN 
IbUbn  «•  *BBCabc*i 

Regardless  of  the  values  of  upptrOniy  and 
louarOniy,  the  boolean  expressions  in  the  three 
IF. .THEN  statements  need  to  be  checked.  In  the 
nested  version,  if  upparOniy  is  TRUE  then  loutrOniy 
will  never  be  checked.  For  greatest  efficiency, 
the  most  likely  case  should  be  the  first  one 


tested  in  a nested  IF...THEN  statement.  If  that 
likely  case  is  true,  no  further  testing  will  be 
done. 

To  avoid  ambiguity  in  parsing  the  nested 
IF..THEN..ELSE  construction,  the  following  rule  is 
used:  Each  ELSE  matches  up  with  the  last 
unmatched  THEN.  So  that 

IF  (xpl  THEN  IF  «xp2  THEN  il  ELSE  »2  ; 

will  group  the  ELSE  with  the  second  THEN  which 
is  equivalent  to 

IF  «xpl  THEN 
BEGIN 

IF  *xp2  THEN  tl  ELSE  t2| 

END; 

and  also  equivalent  to 

IF  «xpl  RNO  *xp2  THEN  (1; 

IF  pxpl  RNO  NOT  «xp2  THEN  t2;  . 

You  can  change  the  structure  with  BEGIN/END  to: 

IF  txpl  THEN 
BEGIN 

IF  *xp2  THEN  il 
ENO  ELSE  i2  | 

which  is  equivalent  to 

IF  ixpl  RNO  txp2  then  (1| 

IF  NOT  txpl  THEN  t2| 

There  is  another  common  use  of  BEGIN/END  in 
IF..THEN  statements.  All  the  examples  so  far 
have  shown  a single  simple  statement  to  be 
executed.  In  fact,  you  often  will  have  a variety 
of  tasks  to  perform  based  on  the  condition 
tested  for.  For  example,  before  you  make  an 
entry  into  an  array,  you  may  want  to  check  that 
you  are  within  the  array  bounds  and  if  so  then 
both  make  the  entry  and  increment  the  pointer 
so  that  it  will  be  ready  for  the  next  entry: 

IF  pokntsr  LEQ  nax  THEM 
BEGIN 

data  [po  Intar)  *■  n#HEntryi 
potnttr«>pointar  ♦ 1} 

ENO 

ELSE  PRINTfftrray  ORTR  It  alraady  full."); 

Here  we  see  the  use  of  a compound  (tatement. 
Compound  statements  are  exactly  like  blocks 
except  that  they  have  no  declarations.  It  would 
also  be  perfectly  acceptable  to  use  a block  with 
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declarations  where  the  compound  statement  is 
used  here  In  fact  both  blocks  and  compound 
statements  ARE  statements  and  can  be  used  ANY 
place  that  a simple  statement  can  be  used.  All  of 
the  statements  between  BEGIN  and  END  are 
executed  as  a unit  (unless  one  of  the  statements 
itself  causes  the  flow  of  execution  to  be 
changed) 


2 A Expressions 

We  have  already  seen  many  of  the  operators 
used  in  expressions.  Sections  4 and  8 of  the  Sail 
manual  cover  the  operators,  the  order  of 
evaluation  of  expressions,  and  type  conversions. 
Appendix  1 of  the  manual  gives  the  word 
equivalents  for  the  single  character  operators, 
eg..  LEO  for  the  less-than-or-equal-to  sign, 
which  are  not  available  except  at  SU-AI.  You 
should  read  these  sections  especially  for  a 
complete  list  of  the  arithmetic  and  boolean 
operators  available  (the  string  operators  will  be 
covered  shortly  in  this  TUTORIAL).  A short 
discussion  of  type  conversion  will  be  given  later 
in  this  section  but  you  should  also  read  these 
sections  in  the  Sait  manual  for  complete  details 
on  type  conversions. 

There  are  three  kinds  of  expressions  that  we 
have  not  used  yet:  assignment,  conditional,  and 
case  expressions.  These  are  much  like  the 
statements  of  the  same  names. 

2 4.1  Assignment  Expressions 

Anywhere  that  you  can  have  an  expression,  you 
may  at  the  same  time  make  an  assignment.  The 
value  will  be  used  as  the  value  of  the  expression 
and  also  assigned  to  the  given  variable.  For 
example: 

IF  (r«ply*INCHUL)  . THEN  

COnnCNT  Inputi  rtply  and  iiaKta  first  fast 
on  It  in  a inq la  alapi 

IF  lcountar,.countar4l)  > aaxEntry  THEN  .... 

COnnENT  updataa  countar  and  chocks  It  lor 
overflow  in  ona  stop) 

countar •■ptr»na»t  loc*.0| 

COnnENT  iniliallzaa  aavaral  varlsbiaa  to  I 
in  ona  atataiaantt 

arry  Ip tr»ptr«ll  ► nawEntry  | 


COnnENT  updataa  ptr  t fills  nant  array 
slot  in  ainqia  atap; 

Note  that  the  assignment  operator  has  low 
precedence  and  so  you  will  often  need  to  use 
parenthesizing  to  get  the  proper  order  of 
evaluation.  This  is  an  area  where  many  coding 
errors  commonly  occur. 

IF  Uj  OR  boola  THEN 

is  parsed  like 

IF  |4(j  OR  boola)  THEN  

rather  than 

IF  (UJ)  OR  boola  THEN 

See  the  sections  in  the  Sail  manual  referenced 
above  for  a more  complete  discussion  of  the 
order  of  evaluation  in  expressions.  In  general  it 
IS  the  normal  order  for  the  arithmetic  operators; 
then  the  logical  operators  AND  and  OR  (so  that 
OR  has  the  lowest  precedence  of  any  operator 
except  the  assignment  operator);  and  left  to  right 
order  is  used  for  two  operators  at  the  same 
level  (but  the  manual  gives  examples  of 
exceptions).  You  can  use  parentheses  anywhere 
to  specify  the  order  that  you  want.  As  an 
example  of  the  effect  of  left-to-right  evaluation, 
note  that 

ind«xtr«>2; 

I (ndtKtr)  ( indextr*- 1 nd«x«r  ♦ 1 ) ; 

will  put  the  value  3 in  <rryi2),  since  the 

destination  is  evaluated  before  mdaxcr  is 

incremented. 

A word  of  caution  is  needed  about  assignment 
expressions.  Make  sure  if  you  put  an  ordinary 
assignment  in  an  expression  that  that  expression 
is  in  a position  where  it  will  ALWAYS  be 

evaluated.  Of  course, 

IF  KJ  THEN  l•.|♦l| 

Will  not  always  increment  i but  this  is  the 

intended  result.  However,  the  following  is 

unintended  and  incorrect; 

IF  v*rbo(«su  THEN 

RRINTI’Th#  tquart  roof  of  ",nui»b,"  l(  ", 
tqroofvSQRT (nuMb) , * .*) 

ELSE  PRINT(tqroof)  | 
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If  v»rbo»«»M  . fBLSt,  the  THEN  portion  is  not 
executed  and  the  assignment  to  iqrooi  is  not 
made.  Thus  tqroot  will  not  have  the  appropriate 
value  when  it  is  PRINTed.  Assigning  the  result  of 
a computation  to  a variable  to  save  recomputing 
it  IS  an  excellent  practice  but  be  careful  where 
you  put  the  assignment. 

Another  very  bad  place  for  assignment 

expressions  is  following  either  the  AND  or  OR 
logical  operators.  The  compiler  handles  these  by 
performing  as  little  evaluation  as  possible  so  in 

•xpl  OR  axp2 

the  compiler  will  first  evaluate  axpl  and  if  it  is 
TRUE  then  the  compiler  Knows  that  the  entire 
boolean  expression  is  true  and  doesn’t  bother  to 
evaluate  pxpZ.  Any  assignments  in  tapj  will  not 
be  made  since  mp2  is  not  evaluated.  (Of  course, 
if  axpi  is  FALSE  then  t>p2  will  be 

evaluated.)  Similarly  for 

•Kpl  RNO  •vp2 

if  pxpi  IS  FALSE  then  the  compiler  Knows  the 
whole  AND-expression  is  FALSE  and  doesn’t 
bother  evaluating  *xp2. 

As  with  nested  IF...THEN...ELSE  statements,  it  is  a 
good  coding  practice  to  choose  the  order  of  the 
expressions  carefully  to  seve  processing.  The 
most  liKely  expression  should  be  first  in  an  OR 
expression  and  the  least  liKely  first  in  an  AND 
expression. 


2.4.2  Conditional  Expressions 

Conditionals  can  also  be  used  in  expressions. 
These  have  a more  rigid  structure  than 
conditional  statements.  It  must  be 

IF  boolaan  pxprptdpn  TMCN  pxpl  ELSE  •xp2 

where  the  ELSE  is  not  optional. 

N.  B.  The  type  of  a conditional  expression  is  the 
type  of  axpi.  If  •»p2  is  evaluated,  it  will  be 
converted  to  the  type  of  PKai.  (At  compile  time 
it  is  not  Known  which  will  be  used  so  an 
arbitrary  decision  is  made  by  always  using  the 
type  of  •xpl.)  Thus  the  statement, 
x-iF  «iP9  THEN  2 ELSE  yi  , Will  always  assign  an 
INTEGER  to  X.  If  X and  y are  REALs  then  y is 


converted  to  INTEGER  and  then  converted  to 
REAL  lor  the  assignment  to  x. 
*-IF  (l«q  THEN  2 ELSE  3.5|  will  assign  either  2.S 
or  3.S  to  X (assuming  x is  REAL).  Examples  are: 

REAL  ARRAY  rtiulti 

Uiir  ainlv«riion  THEN  i$  ELSE  160] ^ 

PRINT  (IF  found  THEN  words tl] 

ELSE  *Uord  not  found."); 

COFIflENT  Mordth)  iiual  b«  a strtnqi 

profit  If  (not  ••  incosto-cotl > > 0 THEN  not 
ELSE  0; 

These  conditional  expressions  will  often  need  to 
be  parenthesized. 


2.4.3  CASE  Expressions 

CASE  statements  are  described  in  Section 

2.6.4  below.  CASE  expressions  are  also 
allowed  with  the  format: 

CASE  int*9«r  Of  (•xpe,«xpl *xpN) 

where  the  first  case  is  always  0.  This  taKes  the 
value  you  give  which  must  be  an  integer 
between  0 and  N and  uses  the  corresponding 
expression  from  the  list.  A frequent  use  is  for 
error  handling  where  each  error  is  assigned  a 
number  and  the  number  of  the  current  error  is 
put  in  a variable.  Then  a statement  liKe  the 
following  can  be  used  to  print  the  proper  error 
message: 

PRINT  (CASE  (rmo  OF 

(”Z«rp  division  •ftomptod*, 

"No  nogs  ft  VO  nu'^iors  sHowod", 

"Input  not  S ‘Jtoor") ) ; 

Remember  that  arme  here  must  range  from  0 to 
2;  otherwise,  a case  overflow  occurs. 


2.4.4  String  Operators 
The  STRING  operators  are: 

EQU  T«tl  for  tlrlny  aqualllyi 

•.'RBC*i  l.*abe*i  t«it»E0U(a, t> | 
RESULT!  tail  • FRLSE  . 
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Conc<t*n4ti  (ho  ilrinqi  (oqothtri 

RESULTi  EQU(u,*«bcd«('l  . TRUE  . 

Rolurna  (ht  Idnfth  o(  « Xringi 
i.-»bc'|  ULENCTH(»)| 

RESULT:  i . 3 . 

Ronovbs  (ho  (irit  eb(r  in  « itring 
and  ro  turng  I 1 1 
»^"abc"i  (••LOPCa); 

RESULT;  (EQU(t,"bc")  BND 

E0U(1,"4"))  • true  . 

Although  LtrJGTH  and  LOP  look  like  procedures 
syntactially,  they  actually  compile  code  ’’in-line". 
This  means  that  they  compile  very  fast  code. 
However,  one  unfortunate  side-effect  is  that  LOP 
cannot  be  used  as  a statement,  i.e.,  you  cannot 
say  LOP(s);  if  you  just  want  to  throw  away  the 
first  character  of  the  string.  You  must  always 
either  use  or  assign  the  character  returned  by 
LOP  even  if  you  don’t  want  it  for  anything,  e.g., 
juni.LOPis);  . Another  point  to  note  about  LOP  is 
that  it  actually  removes  the  character  from  the 
original  string  If  you  will  need  the  intact  string 
again,  you  should  make  a copy  of  it  before  you 
start  LOP’ing,  e g.,  ibiiiiiCopij-ti  . 

A little  background  on  the  implementation  of 
strings  should  help  you  to  use  them  more 
efficiently.  Inefficient  use  of  strings  can  be  a 
significant  inefficiency  in  your  programs.  Sail 
sets  up  an  area  of  memory  called  string  space 
where  all  the  actual  strings  are  stored.  The 
runtime  system  increases  the  size  of  this  area 
dynamically  as  it  begins  to  become  full.  The 
runtime  system  also  performs  garbage  collections 
to  retrieve  space  taken  by  strings  that  are  no 
longer  needed  so  that  the  space  can  be  reused. 
The  text  of  the  strings  is  stored  in  string  space. 
Nothing  IS  put  in  string  space  until  you  actually 
specify  what  the  string  is  to  be,  i.e.,  by  an 
assignment  statement.  At  the  time  of  the 

declaration,  nothing  is  put  in  string  space. 
Instead  the  compiler  sets  up  a 2-word  itring 
descriptor  for  each  string  declared.  The  first 
word  contains  in  its  left-half  an  indication  of 
whether  the  string  is  a constant  or  a variable 
and  in  its  right-half  the  length  of  the  string.  The 
second  word  IS  a byte  pointer  to  the  location  of 
the  start  of  the  string  in  string  space.  At  the 
time  of  the  declaration,  the  length  will  be  zero 
and  the  byte  pointer  word  will  be  empty  since 
the  string  is  not  yet  in  string  space. 


From  this  we  can  see  that  LENGTH  and  LOP  are 
very  efficient  operations.  LENGTH  picks  up  the 
length  from  the  descriptor  word;  and  LOP 
decrements  the  length  by  1,  picks  up  the 
character  designated  by  the  byte  pointer,  and 
increments  the  byte  pointer.  LOP  does  not  need 
to  do  anything  with  string  space.  Concatenations 
with  & are  however  fairly  inefficient  since  in 
general  new  strings  must  be  created.  For  ■ s i, 
there  IS  usually  no  way  to  change  the  descriptor 
words  to  come  up  with  the  new  string  (unless  t 
and  I are  already  adjacent  in  string  space). 
Instead  both  > and  i must  be  copied  into  a new 
string  in  string  space.  In  general  since  the 
pointer  is  kept  to  the  beginning  of  the  string,  it 
IS  less  expensive  to  look  at  the  beginning  than 
the  end.  On  the  other  hand,  when  concatenating, 
it  IS  better  to  keep  building  onto  the  end  of  a 
given  string  rather  than  the  beginning.  The 
runtime  routines  know  what  is  at  the  end  of 
string  space  and,  if  you  happen  to  concatenate 
to  the  end  of  the  last  string  put  in,  the  routines 
can  do  that  efficiently  without  needing  to  copy 
the  last  string. 

Assigning  one  string  variable  to  another,  e.g.,  for 
making  a temporary  copy  of  the  string,  is  also 
fast  since  the  string  descriptor  rather  than  the 
text  IS  copied. 

These  are  general  guidelines  rather  than  strict 
rules.  Different  programs  will  have  different 
specific  needs  and  features. 


2.4.5  Substrings 

Sail  provides  a way  of  dealing  with  selected 
subportions  of  strings  called  substrings.  There 
are  two  different  ways  to  designate  the  desired 
substring: 

■II  TO  j) 

■(i  FOR  j) 

where  (i  to  j)  means  the  substring  starting  at 
the  ith  character  in  the  string  through  the  jth 
character  and  fi  FOR  j)  is  the  substring  starting 
at  the  ith  character  that  is  j characters  long. 
The  numbering  starts  with  1 at  the  first 
character  on  the  left.  The  special  symbol  INF  can 
be  used  to  refer  to  the  last  character  (the 
rightmost)  in  the  string.  So,  tCINF  FOR  II  is  the 
last  character)  and  iI7  to  INF)  is  all  but  the  first 
SIX  characters.  If  you  are  using  e substring  of  a 
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length 


LOP 
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string  array  element 

then 

the  format  IS 

Arr^ ( 1 nd«x) C 1 TO  j). 

Suppose  you  have 

made 

the  'ssign.  lent 

a » ‘abcdal*  . Then, 

ill  TO  31 

(s 

■abc* 

iI2  FOR  3) 

It 

‘bed* 

ill  TO  INFl 

it 

‘abedat* 

ilINF-1  TO  INFl 

It 

■of* 

ill  TO  '3]«‘X*tiI4  TO 

INF]  It 

‘abeXdat*  . 

Since  substrings  are  parts  of  the  text  of  their 
source  strings,  it  is  a very  cheap  operation  to 
break  a string  down,  but  is  fairly  expensive  to 
build  up  a new  string  out  of  substrings. 


2.A.6  Type  Conversions 

If  you  use  an  expression  of  one  type  where 
another  type  was  expected,  then  automatic  type 
conversion  is  performed.  For  example, 

iNTccra  ij 

I > SORT (S) I 

will  cause  5 to  be  converted  to  real  (because 
SORT  expects  a real  argument)  and  the  square 
root  of  5.0  to  be  automatically  converted  to  an 
integer  before  it  is  assigned  to  i which  was 
declared  as  an  integer  variable  and  can  only 
have  integer  values.  As  noted  in  Section  A.2  of 
the  Sail  manual,  this  conversion  is  done  by 
truncating  the  real  value. 

Another  example  of  automatic  type  conversion 
that  we  have  used  here  in  many  of  the  sample 
programs  is: 

IF  reply  • *Y"  THEN  

where  the  - operator  always  expects  integer  or 
real  arguments  rather  than  strings.  Both  the 
value  of  the  string  variable  reply  and  the  string 
constant  'V  will  be  converted  to  integer  values 
before  the  equality  test.  The  manual  shows  that 
this  conversion,  string-to-integer,  is  performed 
by  taking  the  first  character  of  the  string  and 
using  its  ASCII  value.  Similarly  converting  from 
integer  to  string  is  done  by  interpreting  the 
integer  (or  just  the  rightmost  seven  bits  if  it  is 
less  than  0 or  it  is  too  large--that  is  any  number 
over  127  or  ’177)  as  an  ASCII  code  and  using  the 
character  that  the  code  represents  as  the  string. 
So,  for  example. 


STRING  i; 

t > 'lei  a 'll?  a 'iisi 
will  make  the  string  "ABC" 

The  other  common  conversions  that  we  have 
seen  are  integer/real  to  boolean  and  string  to 
boolean.  Integers  and  reals  are  true  if  non-zero; 
strings  are  true  if  they  have  a non-zero  length 
and  the  first  character  of  the  string  is  not  the 
NUL  character  (which  is  ASCil  code  0). 

You  may  also  call  one  of  the  built-in  type 
conversion  procedures  explicitly.  We  have  used 
eVD  extensively  to  convert  strings  containing 
digits  to  the  integer  number  which  the  digits 
represent.  CVD  and  a number  of  other  useful 
type  conversion  procedures  are  described  in 
Section  8.1  of  the  Sail  manual.  Also  this  section 
discusses  the  SETFORMAT  procedure  which  is 
used  for  specifying  the  number  of  leading  zeroes 
and  the  maximum  length  of  the  decimal  portion  of 
the  real  when  printing.  SETFORMAT  is  extremely 
useful  if  you  will  be  outputting  numbers  as 
tables  and  need  to  have  them  automatically  line 
up  vertically. 


2.5  Scope  of  Blocks 

So  far  we  have  seen  basically  only  one  use  of 
inner  blocks.  With  the  IF..THEN  statement,  we 
saw  that  you  sometimes  need  a block  rather  than 
a simple  statement  following  the  THEN  or  ELSE 
so  that  a group  of  statements  can  be  executed 
as  a unit. 

In  fact,  blocks  can  be  used  within  the  program 
any  place  that  you  can  use  a single  statement. 
Syntactically,  blocks  are  statements.  A typical 
program  might  look  like  this: 

KECIN  "proq" 


BEGIN  ' In  1 1 1* I li*l Ion* 


END  ’Inmallzanon* 
BEGIN  ‘Min  part* 

BEGIN  ‘precaif  data* 


BEGIN  ‘output  raaultf* 
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iNO  "output  rotuitt* 
fNO  "procoti  data” 

tNO  "iia  in  par  t" 

BCC  IN  "finish  up* 

END  "finish  up" 

END  "prog" 

The  declarations  in  each  block  establish  variables 
which  can  only  be  used  in  the  given  block.  So 
another  reason  for  using  inner  blocks  is  to 
manage  variables  needed  for  a specific  short 
range  task. 

Each  block  can  (should)  have  a block  name.  The 
name  is  given  in  quotes  following  the  BEGIN  and 
END  of  the  block.  The  case  of  the  letters, 
number  of  spaces,  etc.  are  important  (as  in  string 
constants)  so  that  the  names  "MAIN  LOOP", 
"Mam  Loop",  "mam  loop",  and  "Main  loop"  are  all 
different  and  will  not  match.  There  are  several 
advantages  to  using  block  r\ames’.  your  programs 
are  easier  to  read,  the  names  will  be  used  by  the 
debugger  and  thus  will  make  debugging  easier, 
and  the  compiler  will  check  block  names  and 
report  any  mismatches  to  help  you  pinpoint 
missing  end’s  (a  very  common  programming 
error). 

The  above  example  shows  us  how  blocks  may 
nest.  Any  block  which  is  completely  within  the 
scope  Of  another  block  is  said  to  be  nested  in 
that  block.  In  any  program,  all  of  the  inner 
blocks  are  nested  m the  outer  block.  Here,  in 
addition  to  all  the  blocks  being  within  the  "prog" 
block,  we  find  "output  results"  nested  in 
"process  data"  and  both  "output  results"  and 
"process  data"  nested  m "main  part".  The  three 
blocks  called  "initialization",  "main  part"  and 
"finish  up"  are  not  nested  with  relation  to  each 
other  but  are  said  to  be  at  the  same  l•v•l.  None 
of  the  variables  declared  in  any  of  these  three 
blocks  is  available  to  any  of  the  others.  In  order 
to  have  a variable  shared  by  these  blocks,  we 
need  to  declare  it  in  a block  which  is  "outer"  to 
all  of  them,  which  is  in  this  case  the  very 
outermost  block  "prog". 

Variables  are  available  in  the  block  in  which  they 
are  declared  and  in  all  the  blocks  nested  in  that 


block  UNLESS  the  inner  block  also  has  a variable 
of  the  same  name  declared  (a  very  bad  idea  m 
general).  The  portion  of  the  program,  i.e.,  the 
blocks.  In  which  the  variable  is  available  is  called 
the  scope  of  the  variable. 

BECIN  'Min’ 

INTECea  I,  it 

i *-S } 

i*-2| 

PRINTl'CflSE  Ri  i.’, I,"  J»', j>| 

BEGIN  "lnn«r" 

INTEGER  i,  X, 

1-18) 

PRINTI’CRSE  Bi  l•',l,* 

J-*l 

END  *inn»r'  | 

PRINTCCRSE  Ct  l•■,l,■ 

END  'Min' 

Here  we  cannot  access  k except  in  block  "inner". 
The  variable  j is  the  same  throughout  the  entire 
program.  There  are  2 variables  both  named  i. 
So  the  program  will  print  out; 

CRSE  Ri  I.S  j>2 
CRSE  6i  ib10  k>3 

CftSC  Z\  )-4 

Variables  are  referred  to  as  local  variables  in  the 
block  in  which  they  are  declared.  They  are 
called  global  variables  in  relation  to  any  of  the 
blocks  nested  in  the  block  of  their  declaration. 
With  both  a local  and  a global  variable  of  the 
same  name,  the  local  variable  takes  precedence. 
There  are  three  relationships  that  a variable  can 
have  to  a block: 

1)  It  is  inaccessible  to  the  block  if 
the  variable  is  declared  in  a block  at  the 
same  level  as  the  given  block  or  it  is 
declared  in  a block  nested  within  the 
given  block. 

2)  It  is  local  to  the  block  if  it  is 
declared  in  the  block. 

3)  It  is  global  to  the  block  if  it  is 
declared  in  one  of  the  blocks  that  the 
given  block  is  nested  within. 


Often  the  term  "global  variables"  is  used 
specifically  to  mean  the  variables  declared  in  the 
outer  block  which  are  global  to  all  the  other 
blocks. 
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In  reading  the  Sail  manual,  you  will  see  the 
terms:  allocation,  doallocation,  initialiiation,  and 
rolnitiilizatlon.  It  is  not  important  to  completely 
understand  the  implementation  details,  but  it  is 
extremely  important  to  understand  the  effects. 
The  key  point  is  that  allocating  storage  for  data 
can  oe  handled  m one  of  two  ways.  Storage 
allocation  refers  to  the  actual  setting  up  of  data 
locations  in  memory.  This  can  be  done  1)  at 
compile  time  or  2)  at  runtime.  If  it  is  done  at 
runtime  then  we  say  that  the  allocation  is 
dynamic.  Basically,  it  is  arrays  which  are 
dynamically  allocated  (excluding  outer  block 
arrays  and  other  arrays  which  are  declared  as 
OWN).  LISTS,  SETS,  and  RECORDS  which  we  have 
not  discussed  in  this  section  are  also  allocated 
dynamically.  The  following  are  allocated  at 
compile  time  and  are  NOT  dynamic:  scalar 
variables  (INTEGER,  BOOLEAN,  REAL  and  STRING) 
except  where  the  scalar  variable  is  in  a 
recursive  procedure,  outer  block  arrays,  and 
other  OWN  arrays.  ALCjOL  users  should  note  this 
as  an  important  ALC50L/Sail  difference. 

Dynamic  storage  (inner  block  arrays,  etc.)  will  be 
allocated  at  the  point  that  the  block  is  entered 
and  deallocated  when  (he  block  is  exited.  This 
makes  for  quite  efficient  use  of  large  amounts  of 
storage  space  that  serve  a short  term  need. 
Also,  it  allows  you  to  set  variable  size  bounds 
for  these  arrays  since  the  value  does  not  need 
to  be  known  at  compile  time. 

At  the  time  that  storage  is  allocated,  it  is  also 
initialized.  This  means  that  the  initial  value  is 
assigr>ed-— NULL  for  strings  and  0 for  integers, 
reals,  and  booleans.  Since  arrays  are  allocated 
each  time  the  block  is  entered,  they  are 
reinitialized  each  time.  We  have  not  yet  seen 
any  cases  where  the  same  block  is  executed 
more  than  once  but  this  is  very  frequent  with 
the  iterative  and  looping  control  statements. 

Scalar  variables  and  outer  block  arrays  are  not 
dynamically  allocated.  They  are  allocated  by  the 
compiler  and  wil'  receive  the  inital  null  or  zero 
value  when  the  program  is  loaded  but  they  will 
never  be  reinitialized.  While  you  are  not  in  the 
block,  the  variables  are  not  accessible  to  you  but 
they  are  not  deallocated  so  they  will  have  the 
same  value  when  you  enter  the  block  the  next 
time  as  when  you  exited  it  on  the  previous  use. 
usually  xuu  will  find  that  this  is  not  what  you 
want.  You  should  initialize  all  local  scalar 
variables  yourself  somewhere  near  the  start  of 
the  block-'usually  to  NULL  for  strings  and  0 for 


arithmetic  variables  unless  you  need  some  other 
specific  initial  value.  You  should  also  initialize  all 
global  scalars  (and  outer  block  arrays)  at  the 
start  of  your  program  to  be  on  the  safe  side. 
They  are  initialized  for  you  when  the  compiled 
program  is  later  run,  but  their  values  will  not  be 
reinitialized  if  the  program  is  restarted  while 
already  in  core  and  the  results  will  be  very 
strange. 

One  exception  is  the  blocks  in  RECURSIVE 
PRC)CEDUREs  which  do  have  all  non-OWN 
variables  properly  handled  and  initialized  as 
recursive  calls  are  made  on  the  blocks. 

If  you  should  want  to  clear  an  array,  the 
command 

fiRRCLH  l*rry> 

will  clear  arry  (set  string  arrays  to  NULL  and 
arithmetic  to  0).  For  arithmetic  (NOT  string) 
arrays, 

ARRCLR («rr^, vR I ) 

will  set  the  elements  of  arry  to  vai. 

See  Sections  2.2-2.A  of  the  Sail  manual  for  more 
information  on  OWN,  SAFE,  and  PRELOADED 
arrays  and  Section  8.5  for  the  ARRBLT  and 
ARRTRAN  routines  for  moving  the  contents  of 
arrays. 


2.6  More  Control  Statements 
2.6.1  FOR  Statement 

The  FOR  statement  is  used  for  a definite  number 
of  iterations.  Many  times  you  will  want  to 
repeat  certain  code  a specific  number  of  times 
(where  usually  the  number  in  the  sequence  of 
repetitions  is  also  important  in  the  code 
performed).  For  example, 

roe  I > 1 STEP  1 UNTIL  S 00 
PPINTCI,  • ■,  $QPT(I))| 

which  will  print  out  a table  of  the  square  roots 
of  the  numbers  1 to  5. 

The  syntax  of  the  (simple)  FOR  statement  is 

roe  varlabla  - atari  Ine-valut  STEP  Incrtnant 
UNTIL  tnd-valua  00  alalaiwnt 
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The  itaration  variablo  is  assigned  the  slarting- 
value  and  tested  to  check  if  it  exceeds  the  end- 
value;  if  it  IS  within  the  range  then  the  statement 
after  the  DO  is  executed  (otherwise  the  FOR 
statement  is  finished)  This  completes  the  first 
execution  of  the  FOR-loop. 

Next  the  increment  is  added  to  the  variable  and 
it  IS  tested  to  see  it  it  now  exceeds  the  end- 
value.  If  it  does  then  the  statement  is  not 
executed  again  and  the  FOR  statement  is  finished. 
If  it  IS  within  the  maximum  (or  equal  to  it)  then 
the  statement  is  executed  again  but  all  instances 
of  the  iteration  variable  in  the  statement  will 
now  have  the  new  value.  This  incrementing  and 
checking  and  executing  loop  is  repeated  until  the 
iteration  variable  exceeds  the  end-value. 

For  those  users  familar  with  GOTO  statements 
and  LABELS,  the  following  two  program 
fragments  for  computing  »nt  * FRCT(n)  are 
equivalent. 

•ns  1 { 

FOR  < - 2 STEP  1 UNTIL  n DO  «ns  - ans  • i} 

IS  equivalent  to; 

•nx  •.  1) 

I ► 2| 

loopi  IF  I > n THEN  GOTO  bpyond) 

«n(  » ant  • I I 

I - I 4 1| 

GOTO  loop; 

boi^ondi 

There  is  considerable  dispute  on  whether  or  not 
the  use  of  GOTO  statements  should  be 
encouraged  and  if  so  under  what  conditions. 
These  statements  are  available  in  Sail  but  will 
not  be  discussed  in  this  Tutorial. 

Very  often  FOR-loops  are  used  for  indexing 
through  arrays.  For  example,  if  you  are 
computing  averages,  you  will  need  to  add 
together  numbers  which  might  be  stored  in  an 
array.  The  following  program  allows  a teacher 
to  input  the  total  number  of  tests  taken  and  a 
list  of  the  scores;  then  the  program  returns  the 
average  score. 

BEGIN  "avaraqpr* 

REAL  avdraqt;  INTEGER  numbTdalt,  letdl; 

avdriqpxnutibTdi  1 14  total  4|| 

COttflENT  roDoobar  to  Initlollto  vorloblot; 

PRINM'Totol  numbor  of  tootoi  *); 

nuabToo t o-C VO ( INCHUL 1 1 


BEGIN  "uitRrrty" 

INTEGER  flPRAy  tot tScoroi III nuobToi to]  ; 

COnnENT  orrti^  hot  voriablo  boundt  to  outt 
bo  in  inntr  b loch | 

INTEGER  I; 

COnnENT  lor  uit  ot  tho  Ittrotion  vonoblo; 

FOR  I 4 I STEP  I UNTIL  numbTottt  00 
BEGIN  "III lorroy' 

PRINTCTotl  Scort  /■',  I,"  : 
lottScortt I i)  4 CVO(INCHUL); 

END  ■ I 1 I I orroy " ; 

FOR  I 4 1 STEP  I UNTIL  numbTottt  00 
totol4totdl4tottScorotlil ; 

COrtriENT  noto  that  totol  wot  initiolizod  to 
8 abovo; 

END  "utoftrray"; 

IF  numbTostt  noq  0 THEN  0vor0904 toto  I /numbTot  tt ; 

PRINTt'Tho  Ovorayo  it  " , Ovorago , " . " ) ; 

ENO  "avoraqarr. 

In  the  first  Fc/R-loup,  we  see  that  i is  used  in  the 
PRINT  statement  to  tell  the  user  which  test  score 
IS  wanted  then  it  is  used  again  as  the  array 
subscript  to  put  the  score  into  the  i’th  element 
of  the  array.  Similarly  it  is  used  in  the  second 
FOR-loop  to  add  tne  i’th  element  to  the 
cumulative  total. 

The  iteration  variable,  start-value,  increment,  and 
end-value  can  all  be  reals  as  well  as  integers. 
They  can  also  be  negatives  (in  which  case  the 
maximum  is  lanen  as  a minimum).  See  the  Sail 
manual  (or  details  on  other  variations  where 
multiple  values  can  be  given  for  more  complex 
statements  (these  aren’t  used  often).  One  point 
to  note  IS  that  in  Sail  the  end-value  expression  is 
evaluated  each  time  through  the  loop,  while  the 
increment  value  is  evaluated  only  at  the 
beginning  if  it  is  a complex  expression,  as 
opposed  to  a constant  or  a simple  variable.  This 
means  that  (or  efficiency,  if  your  loop  will  be 
performed  very  many  times  you  should  not  have 
very  complicated  expressions  in  the  end-value 
position.  If  you  need  to  compute  the  end-value, 
do  it  before  the  FOR-loop  and  assign  the  value 
to  a variable  that  can  be  used  in  the  FOR-loop  to 
save  having  to  recompute  the  value  each  time. 
This  doesn’t  save  much  and  probably  isn’t  worth 
it  for  5 or  10  iterations  but  for  500  or  1000  it 
can  be  quite  a savings.  For  example  use: 

MK*'  (plr-eHft«t ) /2) 

rOR  i-offMt  STEP  i UNTIL  mx  00  • | 
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ralh«r  than 

FOR  STEP  1 UNTIL  (ptr-oMi*t>/2  00  i| 


2.6.2  WHILE...DO  statement  and  DO...UNTIL 
Statement 

Often  you  will  want  to  repeat  code  but  not  Know 
in  advance  how  many  times.  Instead  the  iteration 
will  be  finished  when  a certain  condition  is  met. 
This  Is  called  indefinite  iteration  and  is  done  with 
either  a WHILE. ..DO  or  a DO... UNTIL  statement. 

The  syntax  of  WHILE  statements  is: 

WHILE  boolaan-axprtitlon  DO  tlPttMnl 

The  boolean  is  checked  and  if  FALSE  nothing  is 
done.  If  TRUE  the  statement  is  executed  and 
then  the  boolean  is  checked  again,  etc. 

For  example,  suppose  we  want  to  check  through 
the  elements  of  an  integer  array  until  we  find  an 
element  containing  a given  number  n; 

INTEGER  RRRRY  arrylliMxI) 
ptr  » 1| 

UHILE  (arrylpirl  NEO  n)  RNO  (ptr  < Mx)  DO 
plr«-ptr«l( 

If  the  array  element  currently  pointed  to  by  ptr 
is  the  number  we  are  looking  for  OR  if  the  ptr  is 
at  the  upper  bound  of  the  array  then  the  WHILE 
statement  is  finished.  Otherwise  the  ptr  is 
incremented  and  the  boolean  (now  using  the  next 
element)  is  checked  again.  When  the  WHILE...DO 
statement  is  finished,  either  ptr  will  point  to  the 
array  element  with  the  number  or  ptr>max  will 
mean  that  nothing  was  found. 

The  WHILE... DO  statement  is  equivalent  to  the 
following  format  with  LABELS  and  the  GOTO 
statement: 

loepi  IF  not  boolaan  axprttplon  THEN 
GOTO  bpyonai 
• taUMnlt 
GOTO  loopi 

append I 

The  DO...UNTIL  statement  is  very  similar  axcept 
that  1}  the  statement  is  always  axecuted  the 
firet  time  and  then  the  check  is  made  before 
each  subsequent  loop  through  and  2)  the  loop 


continues  UNTIL  the  boolean  becomes  true  rather 
than  WHILE  it  is  true.  ' 

00  tlAltMnt  UNTIL  boolcAn-txprttsion 

For  example,  suppose  we  want  to  get  a series  of 
names  from  the  user  and  store  the  names  in  a 
string  array.  We  will  finish  inputting  the  names 
when  the  user  types  a bare  carnage-return 
(which  results  in  a string  of  length  0 from 
INCHWL  or  INTTY). 

00  printi’Npm  r, uui, ' ic  -) 

UNTIL  (LENGTH(namtliKINCHUL)  >6)1 


The  equivalent  of  the  DO...UNTIL  statement  using 
LABELS  and  the  GOTO  statement  is: 

loopi  ll(t•ll■•nt| 

IF  NOT  booippn  pxprpsslon  THEN  GOTO  loop; 

Note  that  the  checks  in  the  WHILE.. .(X)  and 
DO...UNTIL  statements  are  the  reverse  of  each 
other.  WHILE...DO  continues  as  long  as  the 
expression  is  true  but  (X)... UNTIL  continues  as 
long  as  the  expression  is  NOT  true.  So  that 

UHILE  I < IM  00 

is  equivalent  to 


DO UNTIL  I GEO  100 

except  that  the  statement  is  guaranteed  to  be 
executed  at  least  once  with  the  DO...UNTIL  but 
not  with  the  WHILE...DO. 

The  WHILE  and  DO  statements  can  be  used,  for 
example,  to  check  that  a string  which  we  have 
input  from  the  user  is  really  an  integer.  CVD 
stops  converting  if  it  hits  a non-digit  and  returns 
the  results  of  the  conversion  to  that  point  but 
does  not  give  an  error  indication  so  that  a check 
of  this  sort  should  probably  be  done  on  numbers 
input  from  the  user  before  CVD  is  called. 
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INTECfR  nu»b , cbar; 

STRING  BOOLEAN  •rror; 

PRINTC^Typ®  Iht  nuR»b«r  j *)| 

00 

BEGIN 

9rror*-(  PL  SE  ; 

INCHUL  ; 

UHIIE  LENCTHIItmp)  DO 

IF  NOT  re-  LEQ  (char^L0P(1»»p))  LEO  "9") 
THEN  •rror*-TRU£; 

IF  arror  THEN  PRlNT("OopB,  Iry  aq«int  ”)| 
END 

UNTIL  NOT  arrorj 
nump*-C  VO  (rap  { 


2 6.3  DONE  and  CONTINUE  Statements 

Even  with  definite  and  indefinite  iterations 
available,  there  will  still  be  times  when  you  need 
a greater  degree  of  control  over  the  loop.  This 
IS  accomplished  by  the  DONE  and  CONTINUE 
statements  which  can  be  used  in  any  loop  which 
begins  with  DO,  e g., 

r0»  1.1  STtP  1 UNTIL  I DO  ... 

DO  . . . UNTIL  aiip 
uhilt  op  DO  ... 

(See  the  manual  for  a discussion  of  the  NEXT 
statement  which  is  not  often  used.)  DONE  means 
to  abort  execution  of  the  entire  FOR,  (X)...UNTIL 
or  WHILE. ..DO  statement  immediately.  CONTINUE 
means  to  stop  executing  the  current  pass 
through  the  loop  and  continue  to  the  next 
iteration. 

Suppose  a string  array  is  being  used  as  a 
'dictionary’  to  hold  a list  of  100  words  and  we 
want  to  looK  up  one  of  the  words  which  is  now 
stored  in  a string  called  (•rfai; 

TON  1 . 1 STEP  1 until  111  00 

IF  EOUlHOrtfilil  ,Urq«ll  THEN  OONE  | 

IE  i>ies  THEN  PRINTMprqal,'  not  tound.'l) 

If  the  target  is  found,  the  FOR-loop  will  slop 
regardless  of  the  current  value  of  i.  Note  that 
the  iteration  variable  can  be  checked  alter  the 
loop  IS  terminated  to  determine  whether  the 
DONE  forced  the  termination  (i  LEQ  100)  or  the 
target  was  never  found  and  the  loop  terminated 
naturally  (i  > 100). 

If  the  loops  are  nested  then  the  OONE  or 


It 


CONTINUE  applies  to  the  innermost  loop  unless 
there  are  names  on  the  blocks  to  be  executed  by 
each  loop  and  the  name  is  given  explicitly,  e g., 

DONE  'lonaioop".  With  the  DONE  and  CONTINUE 
statements,  we  can  now  give  the  complete  code 
to  be  used  for  the  sample  program  given  earlier 
where  a number  was  accepted  from  the  user  and 
the  square  root  of  the  number  was  returned.  A 
variety  of  error  checks  are  made  and  the  user 
can  continue  giving  numbers  until  finished.  In 
this  example,  block  names  will  be  used  with  CXDNE 
and  CONTINUE  only  where  they  are  necessary 
for  the  correctness  of  the  program;  but  use  of 
block  names  everywnere  is  a good  practice  for 
clear  programming. 

BEGIN  "proq"  STRING  t«mp,rtplyi  INTEGER  numbf 
UHllE  TRUE  DO 

COnnENT  • v«rq  common  construction  which  just 

loops  unt I I D0NE( 

BEGIN  "procsssnumb" 

PRINT("Typs  s numbsr,  <CR>  to  snd,  or  "> 

WHILE  TRUE  00 
BEGIN  "checfrsr" 

IF  NOT  LENCTH(t*mp.rsply*-lNCHUL)  THEN 
DONE  'procsssnumb" { 

IF  rsply  . THEN 
BEGIN 

PR INT C . .hs Ip tsx t B roprompt. . | 

CONTINUEi 

COnnENT  dsfsults  to  "chsclrsr”; 

END; 

WHILE  LENCTHUsmp)  DO 

IF  NOT  ("0-  LEQ  LOPdomp)  LEQ  ’•9’*)  THEN 
BEGIN 

PRINT ("Oops,  try  sgpint  ")| 

CONTINUE  *chscksr*'| 

END; 

IF  (nuinb*>CVO(rtp  ly) ) < 0 THEN 
BEGIN 

PRINT(”Nsqat  lv«,  try  aqam:  *); 

CONTINUE} 

END; 

DONE; 

COnriENT  1 1 all  (ho  chocks  havo  boon 
passod  than  dono| 

END  "chockor"} 

PRlNTfTho  Squaro  Root  of  ”,numb,"  is 
SORT (numb) ,"■")} 

COnnENT  now  MO  qo  back  to  top  of  loop 
for  noxt  input} 

END  "procoisnumb*} 

END  "proq- 

I 

I 
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2.6.4  CASE  Statement 

The  CASE  stalemenf  is  similar  to  the  CASE 
exO''ession  where  SO,Sl^-Sn  represent  the 
statements  to  be  given  at  these  positions. 

CASE  intagar  OF 
BEGIN 
SB, 

; COnnENT  Iha  aMptg  itataiMnl; 

S2| 


Sn 

END; 

where  j’s  are  included  lor  those  cases  where  no 
action  is  to  be  taKen.  Another  version  of  the 
CASE  statement  is: 


CRSE  Inttgar  OF 


BEGIN 

(81 

S8j 

I«) 

S4( 

conrtENT 

c«t«l  c«n  b4  tkippbd; 

(31 

S3, 

COnnENT 

net  b«  In  prd«r{ 

(51 

SS, 

(61  (71 

S6, 

connENT 

I8I 

S8, 

(n) 

Sn 

CN0| 

1 

where  explicit  numbers  in  [^s  are  given  for  the 
cases  to  be  included. 

It  is  very  IMPORTANT  not  to  use  a semi-colon 
after  the  final  statement  before  the  END.  Also, 
dc  NOT  use  CASE  statements  if  you  have  a 
sparse  number  of  cases  spread  over  a wide 

range  because  the  compiler  will  make  a giant 

table,  e.g., 

CASE  number  OF 
BEGIN 

tai  sai 
(laasi  siaas) 

(?aaa)  szaaa 

EN0| 

would  produce  a 2001  word  table! 

Remember  that  the  first  case  is  0 not  1.  An 

example  is  using  a CASE  statement  to  process 

lettered  optiorw: 

INTCCEA  Chari 

PAINTf'Tyae  A.I.C.O,  ar  E i ')| 
charrINCHULi 


CASE  ehar-"«-  OF 

COnnENT  It  a,  and  la  Ihui  cata  8; 

BEGIN 

<cod*  for  fl  optlon>| 

<codo  for  I opUon>{ 

<codo  for  C option> 

END; 


2.7  Procedures 

We  have  been  using  built-in  procedures  and  in 
fact  would  be  lost  without  them  if  we  had  to  do 
all  our  own  coding  for  the  arithmetic  functions, 
the  interactions  with  the  system  like 
Input/Output,  and  the  general  utility  routines  that 
simplify  our  programming.  Similarly,  good 
programmers  would  be  lost  without  the  ability  to 
write  their  own  procedures.  It  takes  a little  time 
and  practice  getting  into  the  habit  of  looking  at 
programming  tasks  with  an  eye  to  spotting 
potential  procedure  components  in  the  task,  but 
it  IS  well  worth  the  effort. 

Often  in  programming,  the  same  steps  must  be 
repeated  in  different  places  in  the  program. 
Another  way  of  looking  at  it  is  to  say  that  the 
same  task  must  be  performed  in  more  than  one 
context.  The  way  this  is  usually  handled  is  to 
write  a procedure  which  is  the  sequence  of 
statements  that  will  perform  the  task.  This 
procedure  itself  appears  in  the  declaration 
portion  of  one  of  the  blocks  in  your  program  and 
we  will  discuss  later  the  details  of  how  you 
declare  the  procedure.  Essentially  at  the  time 
that  you  are  writing  the  statement  portion  of 
your  program,  you  can  think  of  your  procedures 
as  black  boxes.  You  recognize  that  you  have  an 
instance  of  the  task  that  you  have  designed  one 
of  your  procedures  to  perform  and  you  include 
at  that  point  in  your  sequence  of  statements  a 
procedure  call  statement.  The  procedure  will  be 
invoked  and  will  handle  the  task  for  you.  In  the 
simplest  case,  the  procedure  call  is  accomplished 
by  just  writing  the  procedure’s  name. 

For  example,  suppose  you  have  a calculator-type 
program  that  accepts  an  arithmetic  expression 
from  the  user  and  evaluates  it.  At  suitable 
places  in  the  program  you  will  have  checks  to 
make  sure  that  no  divisions  by  zero  are  being 
attempted.  You  might  write  a procedure  called 
ttrtOiv  which  prints  out  a message  to  the  user 
saying  that  a zero  division  has  occurred,  repeats 
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the  current  arithmetic  expression,  and  asKs  if  the 
user  would  liKe  to  see  the  prepared  help  text  for 
the  program.  Lvery  time  you  check  for  zero 
division  anyplace  in  your  program  and  find  it, 
you  will  call  this  procedure  with  the  statement: 

ZproD I V J 

and  it  will  do  everything  it  is  supposed  to  do. 

Sometimes  the  general  format  of  the  task  will  be 
the  same  but  some  details  will  be  different. 
These  cases  can  be  covered  by  writing  a 
parameterized  procedure.  Suppose  that  we 
wanted  something  like  our  i*roOiv  procedure,  but 
more  genera',  that  would  handle  a number  of 
other  kinds  of  errors.  It  still  needs  to  print  out  a 
description  of  the  error,  the  current  expression 
being  evaluated,  and  a suggestion  that  the  user 
consult  the  help  text;  but  the  description  of  the 
error  will  be  different  depending  on  what  the 
error  was  We  accomplish  this  by  using  a 
variable  when  we  write  the  procedure;  in  this 
case  an  integer  variable  for  the  error  number. 
The  procedure  includes  code  to  print  out  the 
appropriate  message  for  each  error  number;  and 
the  integer  variable  »rrno  is  added  to  the 
parameter  list  of  the  procedure.  Each  of  the 
parameters  is  a variable  that  will  need  to  have  a 
value  associated  with  it  automatically  at  the  lime 
the  procedure  is  called.  (Actually  arrays  and 
other  procedures  can  also  be  parameters;  but 
they  will  be  discussed  later.)  We  won’t  worry 
about  the  handling  of  parameters  in  procedure 
declarations  now.  We  are  concerned  with  the 
way  the  parameters  are  specified  In  the 
procedure  call.  Our  procedure  trrorHandiir  will 
have  one  integer  parameter  so  we  call  it  with 
the  expression  fo  be  associated  with  the  integer 
variable  armo  given  in  parentheses  following  the 
procedure  name  in  the  procedure  call.  For 
example, 

• rror  H«nd I «r (0) 

• rrorHjind  <1 ) 

•r r or Hdnd lor (2 ) 

would  be  the  valid  calls  possible  if  we  had  three 
different  possible  errors. 

If  there  is  more  than  one  parameter,  they  are 
put  in  the  order  given  in  the  declaration  and 
separated  by  commas.  (Arguments  is  another 
term  used  for  the  actual  parameters  supplied  in 
a procedure  call.)  Any  expression  can  be  used 
for  the  parameter,  e.g.,  for  the  built-in  procedure 
SORT: 


5QRT(*l 
SQ0T  (riufttb) 

SQHT  (CVDUNCHUL) ) 
SQPl (numo/d  f V I *or ) 


When  Sail  compiles  the  code  for  these  procedure 
calls,  it  first  incluoes  code  to  associate  the 
appropriate  values  in  the  procedure  call  with  the 
variables  given  in  the  parameter  list  of  the 
procedure  oeclaration  and  then  includes  the  code 
to  execute  the  procedure.  When  »rrorH»ndi«r 
PRiNTs  the  error  message,  the  variable  trmo  will 
have  the  appropriate  value  associated  with  it. 
This  IS  not  an  assignment  such  as  those  done  by 
the  assignment  statement  and  we  will  also  be 
discussing  calls  by  REFERENCE  as  well  as  calls  by 
VALUE;  but  we  don’t  need  to  go  into  the  details 
of  the  actual  implementation  --  see  the  manual  if 
you  are  interested  in  how  procedure  calls  are 
implemented  and  arguments  pushed  on  the  stack. 

Just  as  we  often  perform  the  same  task  many 
times  in  a given  program  so  there  are  tasks 
performed  frequently  in  many  programs  by  many 
programmers.  The  authors  of  Sail  have  written 
procedures  for  a number  of  such  tasks  which  can 
be  used  by  everyone.  These  are  the  built-in 
procedures  (CVD,  INCHWL,  etc.)  and  are  actually 
declared  m the  Sail  runtime  package  so  all  that  is 
needed  for  you  to  use  them  is  placing  the 
procedure  calls  at  the  appropriate  places.  Thus 
these  procedures  are  indeed  black  boxes  when 
they  are  used. 

However,  for  our  own  procedures,  we  do  need  to 
write  the  code  ourselves.  An  example  of  a 
useful  procedure  is  one  which  converts  a string 
argument  to  all  uppercase  characters.  First,  the 
program  with  the  procedure  call  to  upp«r  at  the 
appropriate  place  and  the  position  marked  where 
the  procedure  declaration  will  go: 

BEGIN 

STRING  r«ply,name; 

•«»proc«dura  daclirption  haraaaa 

PRINTCTijpa  REflO,  MRITt,  or  SEBRCH:  *)| 
roplyrUpperUNCHUU  I 

IF  EOUIroply, "REflO")  THEN  

ELSE  IF  EQUIr.ply, "WRITE")  THEN  

ELSE  IF  EQUIropI;^, "SEARCH")  THEN 

ELSE  ....  I 

END; 

We  put  the  code  for  the  procedure  right  in  the 
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procedure  declaration  which  goes  in  the 
declaration  portion  of  any  block.  Remember  that 
the  procedure  must  be  declared  in  a block  which 
will  make  it  accessible  to  the  blocks  where  you 
are  going  to  use  it;  in  the  same  way  that  a 
variable  must  be  declared  in  the  appropriate 
place.  Also,  any  variables  that  appear  m the 
code  of  the  procedure  must  already  be  declared 
(even  in  the  declaration  immediately  preceding 
the  procedure  declaration  is  fine). 

Here  IS  the  procedure  declaration  for  upp«r  which 
should  be  inserted  at  the  marked  position  in  the 
above  code: 

STRING  PROCEDURE  upppr  (STRING  rputtrlnq)) 

BEGIN  "upp«r" 

STRING  xmpi  INTEGER  ch«r[ 
tmp*-NULL ; 

UHILE  LENCTH(r«wstrtng)  DO 
BEGIN 

cHar»L0R  (rawt  tr  >ng) } 
tmpa-t»p4(IF  "a"  LEO  char  LEQ 

then  char-'40  ELSE  char); 

END; 

RETURN(tmp); 

END  "uppar"; 

The  syntax  is: 

typa-qua I I < lar  PROCEDURE  Idantlfiar  ; 

• tataiaant 

for  procedures  with  no  parameters  OR 


tgpa-qua M f iar  PROCEDURE  tdantiflar 
( para»atar-l  1st  ) ; atataaant 

where  the  parameter-list  is  enclosed  in  ()’s  and  a 
semi-colon  precedes  the  statement  (which  is 
often  called  the  procedure  body).  The  <type- 
qualifier>'s  will  be  discussed  shortly. 

The  parameter  list  includes  the  names  and  types 
of  the  parameters  and  must  NOT  have  a semi- 
colon following  the  final  item  on  the  list. 
Examples  are: 

PROCEDURE  oMarHalp  j 
INTEGER  PROCEDURE  IlndUord 

(STRING  tarqati  STRING  RRRRY  Mordi)  | 

SinPLE  PROCEDURE  tProrHandlar 
(INTCCCR  arrno)  | 

RECURSIVE  INTEGER  PROCEDURE  factorial 
(INTEGER  rniabar)  | 


PROCEDURE  »or  t£n tr I at 

(INTEGER  ptr,(irtt;  RERL  RRRRY  untortad)  ; 
STRING  PROCEDURE  uppar  (STRING  rawStrtnq)  ; 

Each  of  these  now  needs  a procedure  body. 

PROCEDURE  oHarHalp  ; 

BEGIN  "oftarHafp" 

COnnENT  tha  procadura  nama  tt  usual  Ig  usad 
at  blocit  nama; 

PR|NT(”Uould  gou  Ilka  halp  (Y  or  N)t  "); 

IF  uppar(lNCMUL)  - “Y"  THEN  PR INT  (" . . ha  I p . . " ) 
ELSE  RETURN, 

PRIN'.'(*Uould  gou  Ilka  tiora  halp  (Y  or  N>!  ”), 

IF  uppar (INCMUL)  - "Y*  THEN 
PRINT(". .«ora  halp.."), 

END  "ollarMalp", 

This  offers  a brief  help  text  and  if  it  is  rejected 
then  RETURNS  from  the  procedure  without 
printing  anything.  A RETURN  statement  may  be 
included  in  any  procedure  at  any  time. 
Otherwise  the  brief  help  message  is  printed  and 
the  extended  help  offered.  After  the  extended 
help  message  is  printed  (or  not  printed),  the 
procedure  finishes  and  returns  without  needing  a 
specific  RETURN  statement  because  the  code  for 
the  procedure  is  over.  Note  that  we  can  use 
procedure  calls  to  other  procedures  such  as 
upp.p  provided  that  we  declare  them  in  the 
proper  order  with  upp*r  declared  before 

of  farHatp. 

PR(XEDURE  declarations  will  usually  have  type- 
qualifiers.  There  are  two  kinds:  1)  the  simple 
types-INTEGER,  STRING,  BOOLEAN,  and  REAL  and 
2)  the  special  ones--FORWARD,  RECURSIVE,  and 
SIMPLE. 

FORWARD  is  typically  used  If  two  procedures  call 
each  other.  This  creates  a problem  because  a 
procedure  must  be  declared  before  it  can  be 
called.  For  example,  if  ou.rH.ip  called  uppar,  and 
uppar  also  called  oKarM.ip  then  we  would  need: 

roauRRO  STRING  PROCEDURE  uppar 
(STRING  rauitrinq)  | 

PROCEDURE  offtrHalp  | 

BEGIN  'oHarHalp' 

<codt  (or  oHarHalp  Includinq  cal(  to  uppar> 
END  'oHarHalp'i 

STRING  PROCEDURE  uppar  (STRING  rauatrlnq)  | 
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<coP«  tor  upper  includinq  cetl  1o  otferH«lp> 
END  "upper"! 

The  FOI^WARD  declaration  does  not  include  the 
body  but  does  include  the  parameter  list  (if  any) 
This  declaration  gives  the  compiler  enough 
iriformation  about  the  upper  procedure  for  it  to 
process  the  oUerMeip  procedure.  FORWARD  is 
also  used  v^hen  there  is  no  Order  of  declaration 
of  a series  of  procedures  such  that  every 
procedure  is  declared  before  it  is  used. 
forward  declarations  can  sometimes  be 
eliminated  by  putting  one  of  the  procedures  in 
the  body  of  the  other,  which  can  be  done  if  you 
don't  need  to  use  both  of  them  later. 

RLCURSIVE  IS  used  to  qualify  the  declaration  of 
any  procedure  which  calls  itself.  The  compiler 
will  add  special  handling  of  variables  so  that  the 
values  of  the  variables  in  the  block  are 
preserved  when  the  block  is  called  again  and 
restored  after  the  return  from  the  recursive  call. 
For  example, 

RECUPSIVt  INTEGER  PROCEDURE  Uclorial 
'INTEGER  III 

RETURNCIF  i • e THEN  1 ELSE  lac  lor  i«  I ( i-l  U 1 1 1 

The  compiler  adds  some  overhead  to  procedures 
that  can  be  omitted  if  you  do  not  use  any 
complicated  structures.  Declaring  procedures 
SIMPLE  inhibits  the  addition  of  this  overhead. 
FTowever,  there  are  severe  restrictions  on 
SIMPLE  procedures;  and  also,  BAIL  can  be  used 
more  effectively  with  non-SlMPLE  procedures. 
So  the  appropriate  use  of  SIMPLE  is  during  the 
optimization  stage  (if  any)  after  the  program  is 
debugged.  At  this  time  the  SIMPLE  qualifier  can 
be  added  to  the  short,  simple  procedures  which 
will  save  some  overhead.  The  restrictions  on 
SIMPLE  procedures  are: 

1)  Cannot  allocate  storage 
dynamically,  i.e.,  no  non-OWN  arrays  can 
be  declared  in  SIMPLE  procedures. 

2)  Cannot  do  C50  TO’s  outside  of 
themselves  (the  GO  TO  statement  has  not 
been  covered  here). 

3)  Cannot,  if  declared  inside  Other 
procedures,  make  any  use  of  the 
parameters  of  the  other  procedures. 


Procedures  which  are  declared  as  One  of  the 
simple  types  (REAL,  INTEGER,  BOOLEAN,  or 
STRING)  are  called  typed  procedures  as  opposed 
to  untyped  procedures  (note  that  the  SIMPLE, 
FORWARD,  and  RECURSIVE  qualifiers  have  no 
effect  on  this  distinction).  Typed  procedures  can 
return  values.  Thus  typed  procedures  are  like 
FORTRAN  functions  and  untyped  procedures  are 
like  FORTRAN  subroutines.  The  type  of  the  value 
returned  corresponds  to  the  type  of  the 
procedure  declaration.  Only  a single  value  may 
be  returned  by  any  procedure.  The  format  is 
RETURN!  Kprittion  ) where  the  expression  is 
enclosed  m O's  Procedure  upp«r  which  was 
givt-n  above  is  a typed  procedure  which  returns 
as  its  value  the  uppercase  version  of  the  string. 
Another  example  is: 

REAL  PROCEDURE  *v*r«q*r 

(INTEGER  ARRAY  >cor*i|  INTEGER  Ms)  | 

BEGIN  REAL  total  | INTEGER  l| 

total  - Bj 

FOR  I » 1 STEP  1 UNTIL  max  00 
total  ,.  total  4 acoratll); 

IF  mas  NED  8 THEN  RETURN ( tola  I /max) 

ELSE  REfURNieij 
END  "avaraqar"; 

We  rrnght  have  a variety  of  calls  to  this 
procedure: 

laatAxtraqa  - a,aragtr ( tat tScoras , numbarScorat ) | 
aa  lari^Avaraqa  avaraqar  (aa  lar  laa,  numbarEmp  loyaat ) | 

■ paadA/araqa  4 a ^araqar (spaada, numbarTr  la  I a)  | 

where  taatScoraa,  aalanaa,  and  apaada  are  all 
INTEGER  ARRAYS. 

Procedure  calls  can  always  be  used  as 
statements,  e g., 

11  IF  diviaor«e  THEN  arrorHandlar  (1)  | 

2)  otIarHalp; 

3)  upparltaxt); 

but  as  in  3)  it  makes  little  sense  to  use  a 
procedure  that  returns  a value  as  a statement 
since  the  value  is  lost.  Thus  typed  procedures 
which  return  values  can  also  be  used  as 
expressions,  e g., 

rap Iq4uppar ( INCHUL) | 

PRINT (uppar (nama) ) | 

It  IS  not  necessary  to  have  a RETURN  statement 
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in  untyped  procedures.  If  you  do  have  a RETURN 
statement  in  an  untyped  procedure  it  CANNOT 
specify  a value;  and  if  you  have  a RETURN 
statement  in  a typed  procedure  it  MUST  specify 
a value  to  be  returned.  If  there  is 'no  RETURN 
statement  in  a typed  procedure  then  the  value 
returned  will  be  garbage  for  integer  and  real 
procedures  or  the  null  string  for  string 
procedures;  this  is  not  good  coding  practice. 

Procedures  frequently  will  RETURNttrue)  or 
RETURN(false)  to  indicate  success  or  a problem. 
For  example,  a procedure  which  is  supposed  to 
get  a filename  from  the  user  and  open  the  file 
will  return  true  if  successful  and  false  if  no  file 
was  actually  opened: 

IF  qviFll*  THFN  procxi  s Ir^pu  1 

ELSE  •rrorMand I #r (22)  j 

This  IS  quite  typical  code  where  you  can  see  that 
all  the  tasks  have  been  procedunzed.  Many 
programs  will  have  25  pages  of  procedure 
declarations  and  then  only  1 or  2 pages  of  actual 
statements  calling  the  appropriate  procedures  at 
the  appropriate  times.  In  fact,  programs  can  be 
written  with  pages  of  procedures  and  then  only 
a single  statement  to  call  the  mam  procedure. 

Basically  there  are  two  ways  of  giving 
information  to  a procedure  and  three  ways  of 
returning  information.  To  give  information  you 
can  1)  use  parameters  to  pass  the  information 
explicitly  or  2)  make  sure  that  the  appropriate 
values  are  in  global  variables  at  the  time  of  the 
call  and  code  the  procedures  so  that  they  access 
those  variables.  There  are  several 
disadvantages  to  the  latter  approach  although  it 
certainly  does  have  its  uses. 

First,  once  a piece  of  information  has  been 
assigned  to  a parameter,  the  coding  proceeds 
smoothly.  When  you  write  the  procedure  call, 
you  can  check  the  parameter  list  and  see  at  a 
glance  what  arguments  you  need.  If  you  instead 
use  a global  variable  then  you  need  to  remember 
to  make  sure  it  has  the  right  value  at  the  time  of 
each  procedure  call.  In  fact  in  a complicated 
program  you  will  have  enough  trouble 
remembering  the  name  of  the  variable  This  is 
one  of  the  beauties  of  procedures.  You  can 
think  about  the  task  and  all  the  components  of 
the  task  and  code  them  once  and  then  when  you 
are  in  the  middle  of  another  larger  task,  you  only 
need  to  give  the  procedure  name  and  the  values 
for  all  the  parameters  (which  are  clearly 


specified  in  the  parameter  list  so  you  don’t  have 
to  remember  them)  and  the  subtask  is  taken  care 
Of.  If  you  don’t  modularize  yOur  programs  in  this 
way,  you  are  /ugglmg  too  many  open  tasks  at 
the  same  time.  Another  approach  is  to  tackle  the 
major  tasks  first  and  every  time  you  see  a 
subtask  put  in  a procedure  call  with  reasonable 
arguments  and  then  later  actually  write  the 
procedures  for  the  subtasks.  Usually  a mixture 
of  these  approaches  is  appropriate;  and  you  will 
also  find  yourself  carrying  particularly  good 
utility  procedures  over  from  one  program  to 
another,  building  a library  of  your  own  general 
utility  routines. 

The  second  advantage  of  parameters  over  global 
variables  is  that  the  global  variables  will  actually 
be  changed  by  any  code  within  the  procedures 
but  variables  used  as  parameters  to  procedures 
will  not.  The  changing  of  global  variables  is 
sometimes  called  a tide-effect  of  the  procedure. 

Here  are  a pair  of  procedures  that  illustrate  both 
these  points: 

BOOLEOk  PROCEDURE  Ou«tl  (STRING  >)| 

BEGIN  -Qu.!!' 

IF  . LOP(i)  then  RETURNItrut) 

ELSE  RETURN((«lt«)  I 

END  'Ouail'i 

STRING  ilr; 

BOOLERN  PROCEDURE  0u«>2  | 

BEGIN  -Qu*(2" 

IF  • LOP(itr)  THEN  RETURN(tru») 

ELSE  RETURNUdt*) ; 

END  "0u*i2'i 

The  second  procedure  has  these  problems:  1)  we 
have  to  make  sure  our  string  is  in  the  string 
variable  tir  before  the  procedure  call  and  2)  »ir 
is  actually  modified  by  the  LOP  so  we  have  to 
make  sure  we  have  another  copy  of  it.  With  the 
first  procedure,  the  string  to  be  checked  can  be 
anywhere  and  no  copy  is  needed.  For  example, 
if  we  want  to  check  a string  called  conmand,  we 
give  Quasi (conaand)  and  the  LOP  done  on  the 
string  in  Quail  will  not  affect  comaand. 

Information  can  be  returned  from  procedures  in 
three  ways: 

1)  With  a RETURN(vaiua)  statement. 

2)  Through  global  variables.  You 

may  sometimes  actually  want  to  change  a 


23 


Th«  ALGOL-P«rl  ot  Sail 


SAIL  TUTORIAL 


global  variable.  Also,  procedures  can 
only  return  a single  value  so  if  you  have 
several  values  being  generated  in  the 
procedure,  you  may  use  global  variables 
for  the  others. 

3)  Through  REFERENCE  parameters. 
Parameters  can  be  either  VALUE  or 
REFERENCE  By  default  all  scalar 
parameters  are  VALUE  and  array 
parameters  are  REFERENCE.  Array 
parameters  CANNOT  be  value;  but  scalars 
can  be  declared  as  reference  parameters. 
Value  parameters  as  we  have  seen  are 
simply  used  to  pass  a value  to  the 
variable  which  appears  in  the  procedure. 
Reference  parameters  actually  associate 
the  variable  address  given  in  the 
procedure  call  with  the  variable  in  the 
procedure  so  that  any  changes  made  will 
be  made  to  the  calling  variable. 

PROCEDURE  nani^Rt  turns 
(REFERENCE  INTEGER  i,J,*,l,«il: 

BEGIN 

M»lR4l| 

ENO; 

When  called  with 


turns  (v«r 1 , v^r 2 , v#r3, vSr 4 , v«rS) J 

will  actually  change  the  varl,..,var5 
variables  themselves.  Arrays  are  always 
called  by  reference  This  is  useful;  for 
example,  you  might  have  a 

PROCEDURE  sortsr  (STRING  RRRRY  trnj)  ; 

which  sorts  a string  array  alphabetically. 

It  will  actually  do  the  sorting  on  the 
array  that  you  give  it  so  that  the  array 
will  be  sorted  when  the  procedure 
returns.  Note  that  arrays  cannot  be 
returned  with  the  RETURN  statement  so 
this  eliminates  the  need  for  making  all 
your  arrays  global  as  a means  of 
returning  them. 

See  the  Sail  manual  (Sec.  2)  for  details  on  using 
procedures  as  parameters  to  Other  procedures. 
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SECTION  3 
Macros 


Sail  macros  are  basically  string  substitutions 
made  in  your  source  code  by  the  scannor  during 
compilation.  Think  of  your  source  file  as  being 
read  by  a scanner  that  substitutes  definitions 
into  the  token  stream  going  to  a logical  "inner 
compiler".  Anything  that  one  car',  do  with 
macros,  one  could  have  done  without  them  by 
editing  the  file  differently.  Macros  are  used  for 
several  purposes. 

They  are  used  to  define  named  constants,  e.g., 

SECIN 

RtQUIRt  ’ (Ml  ■ DEL  IHITERS; 

OEf  INE  uiSir*  • 11(81  | 

RTPL  QRRPy  [ItiUkSix*); 


The  {}'s  are  used  as  delimiters  placed  around  the 
right-hand-side  of  the  macro  definition. 
Wherever  the  token  unSut  appears,  the  scanner 
will  substitute  1(8  before  the  code  is  compiled. 
These  substitutions  of  the  source  text  on  the 
right-hand-side  of  the  DEFINE  for  the  token  on 
the  left-hand-side  wherever  it  subsequently 
appears  in  the  source  file  is  called  exparvjing  the 
macro.  The  above  array  declaration  after  macro 
expansion  is: 

BEGIN 

RERl  RRRRV  arn^  (lil(()| 


which  IS  more  efficient  than  using: 

BEGIN  INTEGER  ■axSiiai 
■a>Slia-l(8i 
BEGIN 

RERL  RRRRY  »rrif  [liiMxSila]  | 

Also,  in  this  example,  the  use  of  the  integer 
variable  for  assignment  of  the  aaxSna  means  that 
the  array  bounds  declaration  is  variable  rather 
than  constant  so  it  must  be  in  an  inner  block; 
with  the  macro,  •a<Sii«  is  a constant  so  the  array 
can  be  declared  anywhere. 

Other  advantages  to  using  macros  to  define 


names  for  constants  are  1)  a name  like 
used  in  your  code  is  easier  to  understand  Than 
an  arbitrary  number  when  you  or  someone  else 
IS  reading  through  the  program  and  2)  i"*<Si»« 
will  undoubtedly  appear  in  many  contexts  m the 
program  but  if  it  needs  to  be  changed,  e g.,  to 
200,  only  the  single  definition  needs  changing  If 
you  had  used  100  instead  of  ««<Siz*  throughout 
t^’e  program  then  you  would  have  to  change 
each  100  to  200. 

Before  giving  your  DEFINES  you  should  require 
some  delimiters.  {}{},  [][],  or  <><>  are  good 
choices  If  you  don’t  require  any  delimiters  then 
the  defaults  are  """"  which  are  probably  a poor 
choice  since  they  make  it  hard  to  define  string 
constants.  The  first  pair  of  delimiters  given  in 
the  REQUIRE  statement  are  for  the  right -hand- 
side  of  the  DEFINE.  See  the  Sail  manual  for 
details  on  use  of  the  second  pair  of  delimiters, 

DEFINES  may  appear  anywhere  in  your  program. 
They  are  neither  statements  nor  declarations. 
REQUIRES  can  be  either  declarations  or 
statements  so  they  can  also  go  anywhere  in  your 
program. 

Another  use  of  macros  is  to  define  octal 
characters.  If  you  have  tried  to  use  any  of  the 
sample  programs  here  you  will  have  discovered 
a glaring  bug.  Each  lime  we  have  output  our 
results  with  the  PRINT  statement,  no  account  has 
been  taken  of  the  need  for  a CRLF  (carnage 
return  and  line  feed)  sequence.  So  all  the  lines 
will  run  together.  Here  are  4 possible  solutions 
to  the  problem: 


1) 

PRINTCSonw  (•xl.*,  CIS*’ 

2) 

•>l 

PRINTI’Scm  ICxt. 

3) 

STRING  crlf| 
cr 1 1.- 

"l 

PRINT  CSonw  l•xl.■,e^ll)| 

il 

REQUIRE  -11-  OELiniTERSi 
OEfINE  erit  . !• 

■I| 

PR;NT("So»>«  1»xI  . ■ , er  I f ) I 

The  first  solution  is  hard  to  type  frequently  with 
the  petals.  (In  general,  concatenations  should  be 
avoided  if  possible  since  new  strings  must 
usually  be  created  for  them;  but  in  this  case  with 
only  constants  in  the  concatenation,  it  will  be 
done  at  compile  time  so  that  is  not  a 
consideration.)  The  second  solution  with  the 
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string  extending  to  the  next  line  to  get  the  cril  is 
unwieldy  to  use  in  your  code.  The  fourth 
solution  IS  both  the  easiest  to  type  and  the  most 
efficient. 

You  may  also  want  to  define  a number  of  the 
other  commonly  used  control  characters: 

StQUlRE  "<><.■  DtllimtRSi 

OfFINE  H . <(’1X«N'JLL)>, 

1 I . < CirSNULDx, 
cr  . <C1S«NUU)>, 
lab  . <(’11<NULL)>, 
c 1 10  ■ <’ 17>j 

The  characters  which  will  be  used  as  arguments 
in  the  PRINT  statement  must  be  forced  to  be 
strings.  If  ff  - <’14>  were  used;  then  PRINT(ff) 
would  print  the  number  12  (which  is  ’M)  rather 
fhar,  to  print  a formfeed  because  PRINT  would 
tre.it  the  '14  as  an  integer.  For  all  the  other 
places  that  you  can  use  these  single  character 
definitions,  they  will  work  correctly  whether 
defined  as  strings  or  integers,  e.g., 

IF  ebar  ■ cIlO  THEN  .... 
as  well  as 

IF  char  • II  THEN  

Note  that  string  constants  like  ’15A'12  and 
’liT&NULL  do  not  ordinarily  need  parenthesizing 
but  (’16&’12)  and  Clfl&NULL)  were  used  above. 
This  IS  a little  trick  to  compile  more  efficient 
code.  The  compiler  will  not  ordinarily  recognize 
these  as  string  constants  when  they  appear  in 
the  middle  of  a concatenated  siring,  e.g., 

" linal...*«’15«’lZ«"....lina2...’ 

but  with  the  proper  parenthesizing 

• I inal...'tClS«'l2)l‘....  linaZ...* 

the  compiler  will  treat  the  crif  as  a string 
constant  at  compile  time  and  no\  need  to  do  a 
concatenation  on  '15  and  '12  every  time  at 
runtime. 

Another  very  common  use  of  macros  is  to 
"personalize'  the  Sail  language  slightly.  Usually 
macros  of  this  sort  are  used  either  to  save 
repetitive  typing  of  long  sequences  or  to  make 
the  code  where  they  are  used  clearer.  (Be 
careful-'this  can  be  carried  overboard.) 


Here  are  some  sample  definitions  followed  by  an 
example  of  their  use  on  the  next  line: 

REQUIRE  ■<><>■  OELiniTERSi 

DEFINE  uplo  • (STEP  1 UNTIL>| 

FOR  I uplo  16  00  . . . . } 

DEFINE  I . «C0f1f1ENT>j 

I*.i4l;  I incrpmpnl  l hprp; 

DEFINE  loravpr  . <UHILE  TRUE>| 

lortvpr  00  ....  I 

DEFINE  PII  • <£LSE  IF>| 

IF  ...  THEN  

EIF  THEN 

EIF THEN I 

Macros  may  also  have  parameters: 

DEFINE  Apptnd(x,^)  • <Ma.x  «y>; 

IF  LCNGTH(b)  then  «pp«nd(1,L0P(s)>t 

DEFINE  inc(n)  ■ <(na-n4l)>, 
d«c(n)  ■ <(n*-n-l)>; 

IF  inc(ptr)  < kijkSIz*  THEN 
COnnENT  MBtch  that  you  don't  forgot 

nttdod  paronthtsas  hara; 

DEFINE  ctrl(n)  • <(-n"-'ie0)>; 

IF  char  ■ ctrl(O)  THEN  abortPrtnt; 

As  we  saw  in  some  of  the  sample  macros,  the 
macro  does  not  need  to  be  a complete  statement, 
expression,  etc.  It  can  be  just  a fragment. 
Whether  or  not  you  want  to  use  macros  like  this 
is  a matter  of  personal  taste.  However,  it  is 
quite  clear  that  something  like  the  following  is 
Simply  terrible  code  although  syntactically 
correct  (and  rumored  to  have  actually  occurred 
in  a program): 

DEFINE  prinltr  . <PRINT(>| 
printtr  "Hi  th«r«.*){ 

which  expands  to 

PRINTCHi  lhpr«.’>; 

On  the  other  hand,  those  who  completely  shun 
macros  are  erring  in  the  other  direction.  One  of 
the  best  coding  practices  in  Sail  is  to  DEFINE  all 
constant  parameters  such  as  array  bounds. 
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SECTION  4 
string  Scanning 


We  have  not  yet  covered  Input/Output  which  is 
one  of  the  most  important  topics.  Before  we  do 
that,  however,  we  will  cover  the  SCAN  function 
for  reading  strings.  SCAN  which  reads  existing 
strings  IS  very  similar  to  INPUT  which  is  used  to 
read  in  text  from  a file. 

Both  SCAN  and  INPUT  use  braaK  tables.  When 
you  are  reading,  you  could  of  course  read  the 
entire  file  in  at  once  but  this  is  not  what  you 
usually  want  even  if  the  file  would  all  fit  (and 
with  the  case  of  SCAN  for  strings  it  would  be 
pointless).  A break  table  is  used  to  1)  set  up  a 
list  of  characters  which  when  read  will  terminate 
the  scan,  2)  set  up  characters  which  are  to  be 
omitted  from  the  resulting  string,  and  3)  give 
instructions  for  what  to  do  with  the  break 
character  that  terminated  the  scan  (append  it  to 
the  result  string,  throw  it  away,  leave  it  at  the 
new  beginning  of  the  old  string,  etc  ).  During  the 
course  of  a program,  you  will  want  to  scan 
strings  in  different  ways,  for  example;  scan  and 
break  on  a non-digit  to  check  that  the  string 
contains  only  digits,  scan  and  break  on  linefeed 
(If)  so  that  you  get  one  line  of  text  at  a time, 
scan  and  omit  all  spaces  so  that  you  have  a 
compact  string,  etc.  For  each  of  these  purposes 
(which  will  have  different  break  characters,  omit 
characters,  disposition  of  the  break  character, 
and  setting  of  certain  other  modes  available), 
you  will  need  a different  break  table.  You  are 
allowed  to  set  up  as  many  as  5A  different  break 
tables  in  a program.  These  are  set  up  with  a 
SETBREAK  command. 

A break  table  is  referred  to  by  its  number  (1  to 
54).  The  GETBREAK  procedure  is  used  to  get 
the  number  of  the  next  free  table  and  the 
number  is  stored  in  an  integer  variable. 
GETBREAK  is  a relatively  new  feature. 

Previously,  programmers  had  to  keep  track  of 
the  free  numbers  themselves.  GETBREAK  is 
highly  recommended  especially  if  you  will  be 
interfacing  your  program  with  another  program 
which  IS  also  assigning  table  numbers  and  may 
use  the  same  number  for  a different  table. 
GETBREAK  will  know  about  all  the  table  numbers 
in  use.  You  assign  this  number  to  a break  table 
by  giving  it  as  the  first  argument  to  the 


SETBREAK  function.  You  can  also  use 

RELBREAK(tablea)  to  release  a table  number  for 
reassignment  when  you  no  longer  need  that 
break  table. 

SETBREBr  ( t jb !•#,  "brtair -charac  lara" , 

"oml l-charaelara",  "modat")  ; 

where  the  first  argument  is  an  integer  and  the 
""’s  around  the  other  arguments  here  are  a 
standard  way  of  indicating,  in  a sample 

procedure  call,  that  the  argument  expected  is  a 
string.  For  example: 

REQUIRE  “<><>■  OELiniTERSj 

DEEINE  M • <'12>,  cr  ■ <*1S>,  M • 

INTEGER  IlnaBr,  nonOiqllBr,  noSpacai; 

SETBRERT  (I  intBr>CETBRER):,  l(,  flier,  'inx'); 
SETBRERMnoSpacaa-CETBRERK,  NULL,  " ",  ’ina")! 
SETBRERL(non0i9ll6r..CETBRERr;,  '0123456789’, 

NULL,  'xna')! 

The  characters  in  the  "break-characters"  string 
will  be  used  as  the  break  characters  to  terminate 
the  SCAN  or  INPUT.  SCAN  and  INPUT  return  that 
portion  of  the  initial  string  up  to  the  first 
occurrence  of  one  of  the  break-characters. 

The  characters  in  the  "omit-characters"  string 
will  be  omitted  from  the  string  returned. 

The  "modes"  establish  what  is  to  be  done  with 
the  break  character  that  terminated  the  SCAN  or 
INPUT.  Any  combination  of  the  following  modes 
can  be  given  by  putting  the  mode  letters 
together  in  a string  constant: 

CHARACTERS  USED  FOR  BREAK  CHARACTERS; 

"I"  (inclusion)  The  characters  in  the  break- 
characters  string  are  the  set  of  characters 
which  will  terminate  the  SCAN  or  INPUT. 

"X"  (exclusion)  Any  character  except  those  in 
the  break-characters  string  will  terminate 
the  SCAN  or  INPUT,  e.g.,  to  break  on  any  digit 
use: 

INTEGER  Iblj 

SETBRERX ( tb  UGETBRERk , *0123466789 ', NULL ,"  i ’)  j 
and  to  break  on  any  non-digit  use; 

INTEGER  tbl| 

SE TBRERMtb UGETBRERK,  *0123456789*,  ■*,*x*)  I 
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where  NULL  or  ""  can  be  used  to  indicate  no 
characters  are  being  given  for  that  argument. 

DISPOSITION  OF  BREAK  CHARACTER: 

"S"  (skip)  The  character  which  actually 
terminates  the  SCAN  or  INPUT  will  be 
"skipped"  and  thus  will  not  appear  in  the 
result  string  returned  nor  will  it  be  still  in 
the  original  string 

"A"  (append)  The  terminating  character  will  be 
appended  to  the  end  of  the  result  string. 

"R"  (retain)  The  terminating  character  will  be 
retained  in  its  position  in  the  original  string 
so  that  it  will  be  the  first  character  read  by 
the  next  SCAN  or  INPUT. 

OTHER  tvllSCELLANEOUS  MODES: 

"K"  This  mode  will  convert  characters  to  be  put 
in  the  result  string  to  uppercase. 

"N"  This  mode  will  discard  SOS  line  numbers  if 
any  and  should  probably  be  used  for  break 
tables  which  will  be  scanning  text  from  a file. 
This  IS  a very  good  Sait  coding  practice  even 
if  it  seems  highly  unlikely  that  an  SOS  file 
will  ever  be  given  to  your  program. 

'raiu  1 I -<  Ir  inq'  SCRN  tt'tourc*' , (<b  !•#,  abrekar)| 

In  these  sample  formats,  the  ""’s  mean  the 
argument  is  a string  and  the  fi  prefix  means  that 
the  argument  is  an  argument  by  reference. 

When  you  call  the  SCAN  function,  you  give  it  as 
arguments  1)  the  source  string,  2)  the  break 
table  number  and  3)  the  name  of  an  INTEGER 
variable  where  it  will  put  a copy  of  the 
character  that  terminated  the  scan.  Both  the 
source  string  and  the  break  character  integer 
are  reference  parameters  to  the  SCAN 

procedure  and  will  have  new  values  when  the 
procedure  is  finished.  The  following  example 
illustrates  the  use  of  the  SCAN  procedure  and 
also  shows  how  the  "S",  "A",  and  "R"  modes 
affect  the  resulting  strings  with  the  disposition 
of  the  break  character. 


INTCCER  «pp«ndBr,  rtIPinBr,  brcK«r| 

STBINC  rvftuM,  tkipSir,  AppandStr,  r«t«inStr| 

SCTBRCnr  (sk  ipBra-CCTBREPi:,***,NULL,'‘t'')| 
SETBRCR*^  («pp«ndBr»CETBREAfc,*b\NULL,*b*)t 


SETBREft^ mBr*CETBRERr ; 

•k  (pStra-App^ndStra^rplpinStra-'f  i rs t •tpcond* { 
rtiult  SCAN  (tk  I pS  tr  » ftkipBr,  brchpr); 

COnnENT  E0U(r«tuM.'f  trtt”)  RNO 
EQU (sk  t pS tr , "■•cond” ) ; 

result  SCRN(ppp«ndStr,  Ppp«ndBr,  brcHdr); 
COnnEMT  RWO 

EQU(apptndStr, ”s«cond”)  ; 

result  ••  SCAN  (r«  tp  I nS  tr  , rptPinBr,  brcKpr); 
COnnENT  EQU(r«tul t,*( irtl")  PNO 

EQU (r«  tp inS tr , ‘ptpcond*) } 

COrtnENT  in  ppch  CPSP  Pbovp  brcKpr  • “p* 
pftpr  Ihp  SCPN) 

Now  we  can  look  again  at  the  break  tables  given 
above: 

SE TBREPk^  ( I I npBr , M , ( Mcr , * i n«" ) ; 

This  break  table  will  return  a single  line  up  to 
the  If.  Any  carriage  returns  or  formfeeds 
(usually  used  as  page  marks)  will  be  omitted  and 
the  break  character  is  also  omitted  (skipped)  so 
that  just  the  text  of  the  line  will  be  returned  in 
the  result  string.  The  more  conventional  way  to 
read  line  by  line  where  the  line  terminators  are 
preserved  is 

SETBRERMrtadLini,  If  ,NULL,'ina''), 

Note  here  that  it  is  extremely  important  that  If 
rather  than  cr  be  used  as  the  break  character 
since  it  follows  the  cr  in  the  actual  text. 
Otherwise,  you'll  end  up  with  strings  like 

tPxl  of  I inp<cr> 

<lf>tpxt  of  I tnp<cr> 

<lf> 

instead  of 

tpxt  of  1 mp<cr><( f> 
tpxt  of  I ir>p<cr><  I f > 

After  the  SCAN,  the  brchar  variable  can  be 
either  the  break  character  that  terminated  the 
scan  (If  in  this  case)  or  0 if  no  break  character 
was  encountered  and  the  scan  terminated  by 
reaching  the  end  of  the  source  string. 

00  procptiL  in# (SCPN (ttr,rb«dL  ir>b,brchdr ) > 

UNTIL  NOT  brchpri 
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This  code  would  be  used  if  you  had  a long  mulfi- 
lined  text  stored  in  a string  and  wanted  to 
process  it  one  line  at  a time  with  PROCEDURE 

procattL  in*. 

SCTBKERK  (nonDiqllBr,’tl23*SS7g9’,NULL,‘x**)| 

This  break  table  could  be  used  to  check  if  a 
I number  input  from  the  user  contains  only  digits. 

UHIU  iru*  00 
BEGIN 

PRINT("Typ«  * nunbtri  ")( 
r*ply*INCHULj  1 INTTY  lor  TENEX| 

SCON  Irtp  ly.nonD  19  I iBn  , brcliar ) [ 

IF  brcX*r  THEN 

PR  INT  IhrehariNULl. , " i>  not  t diqit.'.erH) 
ELSE  DONEi 
END; 

Here  the  value  of  breh»r  (converted  to  a string 
constant  since  the  integer  character  code  will 
probably  be  meaningless  to  the  user)  was 
printed  ou!  to  show  the  user  the  offending 
character.  There  are  many  other  uses  of  the 
brchar  variable  particularly  if  a number  of 
characters  are  specified  in  the  break-characters 
string  of  the  break  table  and  different  actions 
are  to  be  taken  depending  on  which  one  actually 
was  encountered. 

S£TBRE«MnoSp*c*t,NUU,"  •.•|na’)| 

Here  there  are  no  break-characters  but  the 
omit-character(s)  will  be  taken  care  of  by  the 
scan,  e^., 

*ir»*a  b c d"i 

r**u I l»SCRN (1 Ir ,neSpac*i,brcH*r) I 

will  return  "abed"  as  the  result  string. 

If  you  need  to  scan  a number  which  is  stored  in 
j string,  two  special  scanning  functions,  INTSCAN 
and  REALSCAN,  have  been  set  up  which  do  not 
require  break  tables  but  have  the  appropriate 
I cocte  built  in: 


I 

( 

I 

I 

I 


tn  V«r  •>  INTSCAN  (*nuMbtr-i  tr  inq*,9brcH*r ) | 
r«alV«r  ••  ACALSCAN(*nu«b«r-Blr  inq”,fbrcb«r>  f 

where  the  integer  or  real  number  read  is 
returned;  and  the  string  argument  after  the  call 
contains  the  remainder  of  the  string  with  the 
number  removed.  We  could  use  INTSCAN  to 
check  if  a string  input  from  a user  is  really  a 
proper  number. 

PtiaT<*Typ*  th*  nuPbpri  *)| 
reply  » iNCHULi  I INTTY  for  TENtX) 


nueb  > INTSCRNIreply, brchar) I 
IF  brchar  THEN  error | 
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SECTION  5 
Input /Output 


5 1 Simple  Terminal  I/O 

We  have  been  domg  mput/output  (I/O)  from  the 
controlling  terminal  with  INCHWL  (or  INTTY  for 
7ENEX)  and  PRINT.  A number  of  other  Teletype 
I/O  routines  are  listed  in  the  Sail  manual  in 
Sections  7 b and  12*7  but  they  are  less  often 
used.  Also  any  of  the  file  I/O  routines  which  will 
oe  covered  ne»t  can  be  used  with  the  TTY: 
•pecified  in  place  of  a file  Before  we  cover  file 
/O,  a few  comments  are  needed  on  the  usual 
terminal  input  and  output. 

The  INCHWL  (INTTY)  that  we  have  used  is  liKe  an 
INPUT  with  the  source  of  input  prespecified  as 
the  terminal  and  the  breaK  characters  given  as 
the  line  terminators.  Should  you  ever  want  to 
looh  at  the  break  character  which  terminated  an 
INCHWL  or  INTTY,  it  will  be  in  a special  variable 
called  tSKIP!  which  the  Sail  runtimes  use  for  a 
wide  variety  of  purposes.  INTTY  will  input  a 
maximum  of  200  characters.  If  the  INTTY  was 
terminated  for  reaching  the  maximum  limit  then 
tSKIP!  will  be  set  to  -1.  Since  this  variable  is 
declared  in  the  runtime  package  rather  than  in 
your  program,  if  you  are  going  to  be  looking  at 
it,  you  will  need  to  declare  it  also,  but  as  an 
EXTERNAL,  to  tell  the  compiler  that  you  want  the 
runtime  variable. 

EXURNfiL  INTEGER  'SMP'i 

PR  I NT ( “Numbtr  lolloutd  by  <CR>  Or  <QLT>1  ")j 

roplyrINCHUL;  I INTTY  (or  TENEX) 

IT  'ST  IP'  ■ er  THEN  

EISE  IF  'SriPi  . alt  THEN  

Altmode  (escape,  enter,  etc.)  is  one  of  the 
characters  which  is  different  in  the  different 
character  sets.  The  standard  for  most  of  the 
world  including  both  TOPS-10  and  TENEX  is  to 
have  altmode  as  '33  At  some  point  in  the  past 
TOPS-10  used  ’176.  This  is  now  obsolete; 
however,  the  SU-AI  character  set  follows  this 
convention  but  does  so  incorrectly.  It  uses  ’175 
as  altmode  This  will  present  a problem  for 
programs  transported  among  sites.  It  also 
partially  explains  why  most  systems  when  they 
believe  they  are  cfealing  with  a MODEL-33 
Teletype  or  other  uppercase  only  terminal  (or 


are  in  ©RAISE  mode  in  TENEX)  will  convert  the 
characters  ’173  to  '176  to  altmodes. 


52  Notes  on  Terminal  I/O  for  TENEX  Sail 
Only 

if  you  are  programming  in  TENEX  Sail,  you  should 
use  INTTY  in  preference  to  the  various  teletype 
routines  listed  in  the  manual  TENEX  does  not 
have  a line  editor  built  in  You  can  get  the 

effect  of  a line  edtor  by  using  INTTY  which 

allows  tne  user  to  edit  his/her  typing  with  the 
usual  TA,  IR,  TX,  etc.  up  until  the  point  where  the 
line  terminator  is  t\ped  If  you  use  INCHWl,  the 
editing  characters  are  only  DEL  to  rubout  one 
character  and  lU  to  start  over.  Efforts  have 
been  made  in  TENEX  Sail  to  provide  line-editing 
where  needed  in  the  various  I/O  routines  when 
accessing  the  controlling  terminal.  Complete 
details  are  contained  in  Section  12  of  the  Sail 
manual. 

TENEX  also  has  a non-standard  use  of  the 

character  set  which  can  occasionally  cause 
problems  The  original  design  of  TENEX  called 
for  replacing  crif  sequences  with  the  ’37 
character  (eol).  This  has  since  been  largely 
abandoned  and  most  TENEX  programs  will  not 
output  text  with  eol’s  but  rather  use  the 

standard  crIf.  Eol’s  are  still  used  by  the  TENEX 
system  itself.  The  Sail  input  routines  INPUT, 
INTTY,  etc.  convert  eol's  to  crif  sequences.  See 
the  Sail  manual  for  details,  if  necessary;  but  in 
general,  the  only  time  that  you  should  ever  have 
a problem  is  if  you  input  from  the  terminal  with 
some  routine  that  inputs  a single  character  at  a 
time,  e g.,  ChARiN.  In  these  cases  you  will  need 
to  remember  that  end-of-line  will  be  signalled  by 
an  eol  rather  than  a cr.  The  user  of  course 
types  a cr  but  TENEX  converts  to  eol;  and  the 
Sail  single  character  input  functions  do  not 
reconvert  to  cr  as  the  other  Sail  input  functions 
do. 


5.3  Setting  Up  a Channel  for  I/O 

Now  we  need  I/O  for  files.  The  input  and  output 
operations  to  files  are  much  like  what  we  have 
done  for  the  terminal  CPRINT  will  write 
arguments  to  a file  as  PRINT  writes  them  to  the 
terminal.  It  is  also  possible  with  the  SETPRINT 
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command  'o  specify  that  you  would  rather  send 
your  PRINT'S  to  a file  for  to  the  terminal  AND  a 
named  file).  See  the  manual  for  details. 

There  are  a number  of  other  functions  available 
for  I/C  in  addition  to  INPUT  and  CPRINT,  but  they 
all  have  one  common  feature  that  we  have  not 
seen  before  Each  requires  as  first  argument  a 
channel  number.  The  CPU  performs  I/O  through 
input/output  channels  Any  device  (TTY;,  LPT:, 
DTA:,  DSK:,  etc.)  can  be  at  the  other  end  of  the 
channel.  Note  that  by  opening  the  controlling 
terminal  (TTY;)  on  a channel,  you  can  use  any  of 
the  input/output  routines  available.  In  the  case 
of  directory  devices  such  as  DSK:  and  DTA:,  a 
filename  is  also  necessary  to  set  up  the  I/O- 
There  are  several  steps  in  the  process  of 
establishing  the  source /destination  of  I/O  on  a 
numbered  channel  and  getting  it  ready  for  the 
actual  transfer.  This  is  the  area  in  which  TOPS' 
10  and  TENEX  Sail  have  the  most  differences  due 
to  the  differences  in  the  two  operating  systems 
Therefore  separate  sections  will  be  included 
here  for  TOPS- 10  and  TENEX  Sail  and  you  should 
read  Only  the  one  relevant  lor  you. 

5.3.1  TOPS- 10  Sail  Channel  and  File 
Handling 

Routines  for  opening  and  closing  files  in  TOPS-10 
Sail  correspond  closely  to  the  UUO’s  available  in 
the  TOPS  '0  system.  The  mam  routines  are: 

CfTCHPN  OeCN  LOOKUP  (NUR  RELEASE 

Additional  routines  (not  discussed  here)  are: 

USETI  USETO  fITRPE  CLOSE  CLOSIR  CLOSO 


6.3.1. 1 Device  Opening 

chan  > CETCHRN; 

CETCHAN  obtains  the  number  of  a free  channel. 
On  a TOPS- 10  system,  channel  numbers  are  0 
through  ’17.  GETCHAN  finds  the  number  of  a 
channel  not  currently  in  use  by  Sail  and  returns 
that  number.  The  user  is  advised  to  use 
GETCHAN  to  obtain  a channel  number  rather  than 
using  absolute  channel  numbers. 

0PtN<ch«n,  'dcvlc**,  M)d«,  tnbuft, 

outbuft,  tcounl^  fbrchdr,  ttof)| 

The  OPEN  procedure  corresponds  to  the  TOPS- 


10  OPEN  (or  INIT)  UUO.  OPEN  has  eight 
parameters.  Some  of  these  refer  to  parameters 
that  the  OPEN  UUO  will  need;  other  parameters 
specify  the  number  of  buffers  desired,  with 
other  UUO’s  called  by  OPEN  to  set  up  this 
buffering;  still  other  parameters  are  internal  Sail 
bookkeeping  parameters. 

The  parameters  to  OPEN  are: 

1)  CHANNEL:  channel  number, 

typically  the  number  returned  by 
GETCHAN. 

2)  "DEVICE":  a string  argument  that 
IS  the  name  Of  the  device  that  is  desired, 
such  as  "DSK"  for  the  disk  or  "TTY"  for 
the  controlling  terminal. 

3)  MODE:  a number  indicating  the 
mode  of  date  transfer.  Reasonable 
values  are:  0 for  characters  and  strings 
and  '14  for  words  and  arrays  of  words. 
Mode  *17  for  dump  mode  transfers  of 
arrays  is  sometimes  used  but  is  not 
discussed  here. 

4)  INBUFS:  the  number  of  input 
buffers  that  are  to  be  set  up. 

6)  0UT8UFS:  the  number  of  output 
buffers. 

6)  COUNT:  a reference  parameter 
specifying  the  maximum  number  of 
characters  for  the  INPUT  function. 

7)  BRCHAR:  a reference  parameter 
in  which  the  character  on  which  INPUT 
broke  will  be  saved. 

8)  EOF:  a reference  parameter 

which  is  set  to  TRUE  when  the  file  is  at 
the  end. 

The  CHANNEL,  "DEVICE",  and  MODE  parameters 
are  passed  to  the  OPEN  UUO:  INBUFS  and 
OUTBUFS  tell  the  Sail  runtime  system  how  many 
buffers  should  be  set  up  for  data  transfers;  and 
the  COUNT,  BRCHAR  and  EOF  variables  are  cells 
that  are  used  by  Sail  bookkeeping.  N.B.:  many  of 
the  above  parameters  have  additional  meanings 
as  given  in  the  Sail  manual.  The  examples  in  this 
section  are  intended  to  demonstrate  how  to  do 
simple  things. 
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RtlEflSE (ch»n) I 

The  RELEASE  function,  which  laKes  the  channel 
number  as  an  argument,  finishes  all  the  input  ancf 
Output  and  makes  the  channel  available  for  other 
use 

The  following  routine  illustrates  how  to  open  a 
device  (m  this  case,  the  device  is  only  the 
telet>pe)  and  output  to  that  device.  The  CPRINT 
function,  which  is  like  PRINT  except  that  its 
output  goes  to  an  arbitrary  channel  destination, 
IS  used 

begin 

integer  OUTCMRNi 

OPENIOUTCHPN  . CElCHfiN,  "Tiy,8,8,2,0.8.8>  i 
COnnENT 

U)  Obtain  a cbannai  numbar,  uiinq 
CETCHPN.  and  it  in  vanabla  OUTCHRN. 

(2)  Spacit^  davica  TTY,  in  Moda  8, 
with  6 input  and  2 output  butfara- 

(3)  Iqnora  tht  COUNT,  BRCMRR,  and  EOF 
variablas,  which  ara  ti^picali^  not  naadad  It 
tho  fila  It  onl^  for  output.  ( 

CPRINTtOUTCHflN,  "tlassaqa  for  OUTCHRN 

*■>  ; 

COnnENT  Rctual  data  transfar.i 

release (OUTCHRN) ( 

COnnENT  Clota  channalt 
ENO; 

The  following  eifample  illustrates  how  to  read 
text  from  a device,  again  using  the  teletype  as 
the  device. 


BEGIN 

INTEGER  INCHRN,  INBRCHRR,  INEOEi 

OPEN  (INCHRN  8-  GETCHRN,  ’TTY",  0,  2,  0,  200, 
INBRCHRR.  INEOOi 

COnnENT 

Opans  tht  tty  in  iioda  0 (charac  tart ) , with 
2 input  buHart,  6 output  buffart.  Rt  most 
209  characttrt  will  ba  raad  in  with  tach 
Input  ttatamtnt,  and  tnt  brtair  charjctar 
will  ba  pul  into  var labia  INBRCHRR.  Tha 
and*of-fiia  Mill  ba  tiqnallad  b<^  INEOP 
bainq  tat  to  TRUE  aftar  toma  call  to  an 
input  function  hat  found  that  thara  it  no 
wort  data  in  tha  f i lai 

UHILE  NOT  INEOF  DO 
BEGIN 

...  coda  to  do  input  taa  balow.  ... 

ENO; 

RELEASE (INCHRN) I 

END} 


5.3.2  Reading  and  Writing  Disk  Files 

Most  input  and  output  will  probably  be  done  to 
the  disk.  The  disk  (and,  typically,  the  DECtape) 
are  directory  devices,  which  means  that  logically 
separate  files  are  associated  with  the  device. 
When  using  a directory  device,  it  is  necessary  to 
associate  a file  name  with  the  channel  that  is 
open  to  the  device. 

LOOrUPICHRN,  "nLENBriE-,  *FLRC)| 

ENTERICHBN,  "EILENBnE",  »FLBC); 

File  names  are  associated  with  channels  by  three 
functions:  LOOKUP.  ENTER,  and  RENAME.  We  will 
discuss  LOOKUP  and  ENTER  here.  Both  LOOKUP 
and  ENTER  take  three  arguments:  a channel 
number,  such  as  returned  by  GETCHAN,  which 
has  already  been  opened;  a text  string  which  is 
the  name  of  the  tile,  using  the  file  name 
conventions  of  the  operating  system;  and  a 
reference  flag  that  will  be  set  to  FALSE  if  the 
operation  is  successful,  or  TRUE  otherwise.  (The 
TRUE  value  is  a bit  pattern  indicating  the  exact 
cause  of  failure,  but  we  will  not  be  concerned 
with  that  here.)  There  are  three  permutations  of 
LOOKUP  and  ENTER  that  are  useful: 

1)  L(X)KUP  alone:  this  is  done  when 
you  want  to  read  an  already  existing  file. 


2)  ENTER  alone:  this  is  done  when 
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you  want  to  write  a tile.  If  a file  already 
exists  with  the  selected  name,  then  a new 
one  IS  created,  and  upon  closing  of  the 
file,  the  old  version  is  deleted  altogether, 
This  IS  the  standard  way  to  write  a file. 

3)  A LOOKUP  followed  by  an  ENTER 
using  the  same  name:  this  is  the  standard 
way  to  read  and  write  an  already 
existing  file. 

The  following  program  will  read  an  already 
existing  text  file,  (eg.,  with  the  INPUT,  REALIN, 
and  INTIN  functions,  which  scan  ASCII  text.)  Note 
that  the  L(X)KUP  function  is  used  to  see  if  the 
file  IS  there,  obtaining  the  name  of  the  file  from 
the  user.  See  below  for  details  about  the 
functions  that  are  used  for  the  actual  reading  of 
the  data  in  the  file. 

BEGIN 

INTEGER  INCMRN,  INBRCHRR,  INEOF,  FEBCj 
STRING  FUENRME; 

OPEN  (INCMRN  . CETCHRN,  ’OSF",  8,  2,  8,  288, 
INBRCHRR,  INEOF) I 

unile  true  00 

BEGIN 

PRINT("Input  III*  •")( 

LOOrUPdNCHRN,  FILENRNE  INCHUL,  FLROi 
IF  FLBG  THEN  DONE  ELSE 
PRINTCC*nnol  (Ind  (il*  ",  FILENRHE, 

• try  «q*in. 

■>l 

END; 

UHILE  not  INEOF  00 
BEGIN  "INPUT* 

....  baloM  (or  rtodinq  choroctorl. . . 

ENO  *INPUT*| 

RELERSE (INCMRN) I 
END; 

The  following  program  opens  a file  for  writing 
characters. 

BEGIN 

INTEGER  OUTCHRN,  FLflC) 

STRING  FILENflnE) 

OPEN  (flUTCMRN  r GETCHRN,  *0SF',  8,  8,  2,  8, 

•.  •>( 

UMIlE  TRUE  00 
BEGIN 

RRINTCOutpul  (ila  naoa  *’)) 


ENTER (OUTCHRN,  F ILENRHE  r INCHUL,  FLRG); 

IF  NOT  FLAG  THEN  DONE  ELSE 
PRINTCConnot  Mrllo  (ilo  ',  FILENfltlE, 

* tr^ 

■)i 

END; 

...  noM  Mr  it#  Iho  ItMl  (0  OUTCHRN  ... 

RELERSE (OUTCHRN); 

EN0| 

5.3.2. 1 Reading  and  Writing  Full  Words 

Reading  36-bit  PDPIO  words,  using  WORDIN  and 
ARRYIN,  and  writing  words  using  WORDOUT  and 
ARRYOUT,  is  accomplished  by  opening  the  file 
using  a binary  mode  such  as  ’lA  We  recommend 
the  use  of  binary  mode,  with  2 or  more  input 
and/or  Output  buffers  selected  in  the  call  to  the 
OPEN  function.  There  are  other  modes  available, 
such  as  mode  ’17  for  dump  mode  transfers;  see 
the  timesharing  manual  for  the  operating  system. 


5.3.22  Other  Input/Output  Facilities 

Files  can  be  renamed  using  the  RENAME  function. 
Some  random  input  and  output  is  offered  by  the 
USETI  and  USETO  functions,  but  random  input  and 
output  produces  strange  results  in  TOPS-10  Sail. 
Best  results  are  obtained  by  using  USETI  and 
USETO  and  reading  or  writing  128-word  arrays 
to  the  disk  with  ARRYIN  and  ARRYOUT. 

Magnetic  tape  operations  are  performed  with  the 
MTAPE  function. 

See  the  Sail  manual  (Sec.  7)  for  more  details 
about  these  functions.  In  particular,  we  stress 
that  we  have  not  covered  all  the  capabilities  of 
the  functions  that  we  have  discussed. 


5.3.3  TENEX  Sail  Channel  and  File  Handling 

TENEX  Sail  has  included  all  of  the  TOPS-10  Sail 
functions  described  in  Section  7.2  of  the  Sail 
manual  for  reasons  of  compatibility  and  has 
implemented  them  suitably  to  work  on  TENEX. 
Descriptions  of  how  these  functions  actually 
work  in  TENEX  are  given  in  Section  12.2  of  the 
manual.  However,  they  are  less  efficient  than 
the  new  set  of  specifically  TENEX  routines  which 
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have  been  added  to  TtNEX  Sail  so  you  probably 
should  skip  these  sections  of  the  manual.  The 
new  TLNEX  routines  are  also  greatly  sirriplified 
for  the  user  so  that  a number  ol  the  steps  to 
establishing  the  I/O  are  done  transparently. 

Basically,  you  only  need  to  Know  three 
commands:  1)  OPLNFILE  which  establishes  a file 
on  a channel,  2)  SETINPUT  which  establishes 
certain  parameters  for  the  subsequent  inputs 
from  the  file,  and  3)  CFILE  which  closes  the  file 
and  releases  the  channel  when  you  are  finished. 

Chari#  ► OPENF  RE  (■)  I l•nam^■,  "inodaj") 

The  OPENFILE  function  takes  2 arguments:  a 
string  containing  the  device  and/or  filename  and 
a string  constant  containing  a list  of  the  desired 
modes.  OPENFILE  returns  an  integer  which  is  the 
channel  number  to  be  used  in  all  subsequent 
inputs  or  outputs.  If  you  give  NULL  as  the 
filename  then  OPENFILE  goes  to  the  user’s 
terminal  to  get  the  name.  (Be  sure  if  you  00  this 
that  you  first  PRINT  a prompt  to  the 
terminal.)  The  modes  are  listed  in  the  Sail 
manual  (Sec.  12.3)  but  not  all  of  those  listed  are 
commonly  used.  The  following  are  the  ones  that 
you  will  usually  give: 

R or  W or  A for  Read,  Write,  or  Append 
depending  on  what  you  intend  to  do 
with  the  file. 

» if  you  are  allowing  multi-file 

specifications,  e g.,  data.*;*  . 

C if  the  user  is  giving  the 

filename  from  the  terminal,  C mode 
will  prompt  for  [confirm]. 

E if  the  user  is  giving  the 

filename  and  an  error  occurs 
(typically  when  the  wrong  filename 
IS  typed),  the  E mode  re, urns 
control  to  yOur  program.  If  E is  not 
specified  the  user  is  automatically 
asked  to  try  again. 

Modes  0 and  N for  Old  or  New  File  are  also 
allowed  but  probably  shouldn’t  be  used.  They 
are  misleading.  The  defaults,  e g.  without  either 
0 or  N specified,  are  the  usual  conditions  (read 
an  old  version  and  write  a new  version).  The  0 
and  N options  are  peculiar.  For  example,  "NW" 
means  that  you  must  specify  a completely  new 
filename  for  the  file  to  be  written,  e g.,  a name 


that  has  not  been  used  before.  N does  not  mean 
a new  version  as  one  might  have  expected.  In 
general,  the  I/O  routines  use  the  relevant  JSYS’s 
directly  and  thus  include  all  of  the  design  errors 
and  bugs  in  the  JSYS’s  themselves. 

INTEGER  inHit,  outfil*,  d«  ( au  I t tF  i I • ; 

PRINT  (*■  Inpu  t n I a t " ) j 
inFfle  OPENFIUCNULL,  Vc“); 

PRINTrOutput  I ( l»:  ")  ; 
outFile  OPENFILE  (NULL,  •'mc"); 
de  (au  1 1 sF  t i • •- 

OPENF  RE  r'u»«r-d#  ( au  I t » . t mp"  , "m"  ) ; 

We  now  have  files  "open"  on  3 channels--one  for 
reading  and  two  for  writing.  We  have  the 
channel  numbers  stored  in  inFile,  outFile,  and 
defaultsFile  so  that  we  can  refer  to  the 
appropriate  channel  for  each  input  or  output. 
Next  we  need  to  do  a SETINPUT  on  the  channel 
open  for  input  (reading). 

SETINPUT (chan#,  count,  ebrehar,  §eol) 


There  are  four  arguments: 

1)  The  channel  number. 

2)  An  integer  number  which  is  the 
maximum  number  of  characters  to  be 
read  in  any  input  operation  (the  default  if 
no  SETINPUT  is  done  is  200). 

3)  A reference  integer  variable 
where  the  input  function  will  put  the 
break  character. 

4)  A reference  integer  variable 
where  the  input  function  will  put  true  or 
false  for  whether  or  not  the  end-of-file 
was  reached  (or  the  error  number  if  an 
error  was  encountered  while  reading). 

So  here  we  need: 

INTEGER  ihlilaBrChr,  infiltEal) 

SETINPUT  (mill#,  260,  infiltbrchr,  infiltEof); 

Now  we  do  the  relevant  input/output  operations 
and  when  finished: 


CE  RE  ( inf  I lb)  { 
CFRE(outlilt); 

CF  RE  (do I #u I loF  I lo)  ( 


I 

I 

I 

I 
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INTECtR  outf  t l«; 

PRINTCTyp#  lor  output: 

out  n (e^OPfNr  UE  fNUU,  "wc-)  J 
CPRINT  (out  1 1 l«,  ’'noftiiq*.  . • *>  i 
CMLE(Dutf  lit)) 

where  CPRINT  is  like  PRINT  except  for  the 
additional  first  argument  which  is  the  channel 
number. 

The  OPENFILF.  SETINPUT,  and  CFILE  commands 
will  handle  most  situations.  If  you  have  unusual 
requirements  or  like  to  get  really  fancy  then 
there  are  many  variations  of  file  handling 
available.  A few  of  the  more  commonly  used  will 
be  covered  m the  next  section;  but  do  not  read 
this  section  until  you  have  tried  the  regular 
routines  and  need  to  do  more  (if  ever).  On  first 
reading,  you  should  now  skip  to  Section  5.4. 


5.3  4 Advanced  TENEX  Sail  Channel  and 
File  Handling 

It  you  want  to  use  multiple  file  designators  with 
*’s,  you  should  give  as  one  of  the  options  to 
OPENFILE.  Then  you  will  need  to  use  INDEXFILE 
to  sequence  through  the  multiple  files.  The 
syntax  is 

found  I anothtr  I I I I*  » INDEXC  HE  (chanf) 

where  lound '•noihtr  1 1 1 It  is  a boolean  variable. 
'NDEXFILE  accomplishes  two  things.  First,  if 
there  is  another  file  in  the  sequence,  it  is 
nroperly  initialized  on  the  channel;  and  second, 
NDEXFILE  returns  TRUE  to  indicate  that  it  has 
gotten  another  file  Note  that  the  original 
OPENFILE  gets  the  first  file  in  the  sequence  on 
the  channel  so  that  you  don't  use  the  INDEXFILE 
until  you  have  finished  processing  the  first  file 
and  are  ready  for  the  second  This  is  done 
conveniently  with  a DO  .UNTIL  where  the  test  is 
not  made  until  after  the  first  time  through  the 
loop,  e g., 


•HjItlFildt  OPENFILE('d<t*.*’,V*'l| 

00 

BEGIN 

...xinpul  and  procdii  current  lllo... 

END 

UNTIL  NOT  INDEXFILEUiulllFlIeili 

Another  available  option  to  the  OPENFILE  routine 
which  you  should  consider  using  is  the  "E"  option 
(or  error  handling.  If  you  specify  this  option  and 


the  user  gives  an  incorrect  filename  then 
OPENFILE  will  return  -1  rather  than  a channel 
number  and  the  TENEX  error  number  will  be 
returned  in  !SKIP!,  Remember  to  declare 
EXTERNAL  INTEGER  ISXIP!  if  you  are  going  to  be 
looking  at  it.  Handling  the  errors  yourself  is 
often  a good  idea.  TENEX  is  unmerciful.  If  the 
user  gives  a bad  filename,  it  will  ask  again  and 
keep  on  asking  forever  even  when  it  is  obvious 
after  a certain  number  of  tries  that  there  is  a 
genuine  problem  that  needs  to  be  resolved. 

Another  use  for  the  ”E"  mode  is  to  offer  the  user 
the  option  of  typing  a bare  <CR>  to  get  a default 
file.  If  the  ”E"  mode  has  been  specified  and  the 
user  types  a carnage-return  for  the  filenarr,e 
then  we  know  that  the  error  number  returned  in 
ISXIP!  will  be  the  number  (listed  in  the  JSYS 
manual)  for  "Null  filename  not  allowed."  so  we 
can  intercept  this  error  and  simply  do  another 
OPENFILE  with  the  default  filename,  e g., 

EXTERNSL  INTEGER  'SFIPI| 

out  1 1 lo*--!; 

UHILE  outtll*  • -1  00 
BEGIN 

PRINTCFl  lonamo  (<CR>  for  TTYi ) •"); 

out  1 1 l»,.0PENF  ILE  (NULL,  'u*')  I 

IF  >tk ipi  • 'eaaiis  then 

ouH  I H-OPENFILE  ("TTYi  - , "u")  I 

ENO; 

The  GTJFNL  and  GTJFN  routines  are  useful  if  you 
need  more  options  than  are  provided  in  the 
OPENFILE  routine,  but  neither  of  these  actually 
opens  the  file  so  you  will  need  an  OPENF  or 
OPENFILE  after  the  GTJFNL  or  GTJFN  unless  your 
purpose  in  using  the  GTJFN  is  specifically  that 
you  do  not  want  to  open  the  file.  The  GTJFNL 
routine  is  actually  the  long  form  of  the  GTJFN 
JSYS;  and  the  GTJFN  routine  is  the  short  form  of 
the  GTJFN  JSYS.  See  the  TENEX  JSYS  manual  for 
details. 

Another  use  of  GTJFNL  is  to  combine  filename 
specification  from  a string  with  filename 
specification  from  the  user.  This  is  a simple  way 
to  preprocess  the  filename  from  the  user,  i.e.,  to 
check  if  it  IS  really  a "?"  rather  than  a filename. 
First,  you  need  to  declare  !SXIP!  and  ask  the  user 
for  a filename: 

external  integer  >SXIPI| 

WHILE  TRUE  00 

BEGIN  "g«tf  I ItnaiM* 

RNINTCTyp*  Input  fllanpiM  or  7 t ")i 
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Next  do  a regular  INTTY  to  get  the  reply  into  a 
string; 

t . INTIV; 

Then  you  process  the  string  in  any  way  that  you 
choose,  e g , checK  il  it  is  a or  some  other 
specia'  keyword: 

If  1 . THEN  begin 

q I -(h* Ipi 

CONTINUE  "qc t ♦ I I inam* " [ 

END; 

If  you  decide  it  is  a proper  filename  and  want  to 
use  it  then  you  give  that  string  (with  the  break 
character  from  INTTY  which  will  be  in  ’SKIP! 
appended  back  on  to  the  end  of  the  string)  to 
the  GTJFNL. 

chan#  . CTJfNL  (sS'SMPi,  '160000008800, 
'000100000101,  NULL,  null.  NULL, 

NULL , NULl , NULL) ; 

If  the  string  ended  m altmode  meaning  that  the 
user  wanted  filename  recognition  then  that  will 
be  done;  and  if  the  string  is  not  enough  for 
recognition  and  more  typein  is  needed  then  the 
GTJFNL  will  ring  the  bell  and  go  back  to  the 
user's  terminal  without  the  user  knowing  that 
any  processing  has  gone  on  in  the  meantime,  i.e., 
to  ttie  user  it  looks  exactly  like  the  ordinary 
QPENFILE  Thus  the  GTJFNL  goes  first  to  the 
string  that  you  give  it  but  can  then  go  to  the 
terminal  if  more  is  needed 

After  the  GTJFNL  don’t  forget  that  you  still  need 
to  OPENF  the  file.  For  reading  a disk  file, 

OPENE  (chan#,  ' «400Oe2eee68l ; 

IS  a reasonable  default,  and  for  writing: 

OPENF  (chant,  ’ «4O6O8ie06OOI ; 

The  arguments  to  GTJFNL  are: 

cH^n#  *•  CT  JFNI  ("  I , flaq«, 

"drr“,  "namt", 

“pro t#c t ion" , "acc ♦ " > ; 

where  the  flag  specification  is  made  by  looking 
up  the  FLAGS  for  the  GTJFN  JSYS  in  the  JSYS 
manual  and  figuring  out  which  bits  you  want 
turned  on  and  which  off.  The  36-bit  resutling 
word  can  be  given  here  in  its  octat 
representation.  '160000000000  means  bits  2 
(old  file  only),  3 (give  messages)  and  ^ (require 


confirm)  are  turned  on.  Remember  that  the  bits 
start  with  Bit  0 on  the  left.  The  jfnjfn  will 
probably  always  be  ’000100000101.  This 
argument  is  for  the  input  and  output  devices  to 
be  used  if  the  string  needs  to  be  supplemented. 
Here  the  controlling  terminal  is  used  for  both. 
Devices  on  the  system  have  an  octal  number 
associated  with  them  The  controlling  terminal  as 
input  device  is  ’100  and  as  output  is  ’101.  For 
m.ost  purposes  you  can  refer  to  the  terminal  by 
its  "name"  which  is  TTY:  but  here  the  number  is 
required.  The  input  and  output  devices  are 
given  in  half  word  format  which  means  that  ’100 
IS  in  the  left  and  ’101  in  the  right  half  of  the 
word  with  the  appropriate  O’s  filled  out  for  the 
rest. 

The  next  six  arguments  to  GTJFNL  are  for 
defaults  if  you  want  to  give  them  for:  device, 
directory,  file  name,  file  extension,  file 
protection,  and  file  account  If  no  default  is 
given  for  a field  then  the  standard  default  (if 
any)  is  used,  e g.,  DSK;  for  device  and  Connected 
Directory  for  oirectory.  This  is  another  reason 
why  you  may  choose  GTJFNL  over  QPENFILE  for 
getting  a filename.  In  this  way,  you  can  set  up 
defaults  for  the  filename  or  extension.  You  can 
also  use  GTJFNL  to  simulate  a directory  search 
path.  For  example,  the  EXEC  when  accepting  the 
name  of  a program  to  be  run  follows  a search 
path  to  locate  the  file  First  it  looks  on 

<?iUBSYS>  for  a file  of  that  name  with  a SAV 
extension.  Next  it  looks  on  the  connected 
directory  and  finally  on  the  login  directory.  If 
you  have  an  analogous  situation,  you  can  use  a 
hierarchical  senes  of  GTJFNL’s  with  the 
appropriate  defaults  specified: 

external  integer  'S» IP': 

INTECE^^  loqtj  tr  , cond  t r , 1 1 qno ; 

STRING  loqdir«!<  .condirttr* 

CJINT ( loqd ir , cond If , 1 1 qno) ; 

COflnENT  putt  th#  d-rtctvrq  nuifbdrt  tpr  Ipqin 
«nd  COnntCt«d  d>r«ctQrq  «nd  in 

«t(  rtf«r«nc*  int«q«p  drquin«nti; 

loqdiritr»DlR$T ( ioqd«r) ; 

Cond*rttr»OIRST (condir) ; 

COnntNT  rttuFTt  s ttrinq  tpr  th#  nAm« 
corrttpondinq  to  dirtctorq#  | 

UHILE  try*  00 
BEGIN  "qotnam#" 

PRINT("7qpt  tho  namo  of  tho  proqram:  "); 

IF  EQU  <upptr(N«nE  INTTY)  , "EXEC")  THEN 

begin 

namo..-«SYSTEn>EXEC.SPV"( 

DONE 

END; 

IF  na«o  . THEN 


36 


I 


SAIL  tutorial 


Input/Output 


i 

.1 

I 

*1 


in 


T 

I 

I 

I 

! 


BEGIN 

q • ' Ip  ; 

CCNT iNUt  "q» • j 
END; 

‘ S*  IP  • ; 

COnrfNT  put  br»^»  CbAr  bACk  onj 

OEFiNC  tiaq  * < ’ ie0eoeeeo0Be>, 

jtnjln  • « ' 100BB0181 

IF  (t#mpCN«o*CTjFNL  » Ijq,  jtnjin,  NULL  , 

"SU6SYS", NULL, "SPV. NULL, NUIL)»  • -1 
THEN 

IF  ( 1 •mpChAn*-CT  JFNI  , H 4q  , 

j In j fn, NULL , cond  ir*  tr , NULL , 

"SPV".NULL .NULL))  • -1  THEN 
IF  ( t•mpChan•>CT  JF  NL  fnam«  , I I Aq  , 
j I n J f n, NULL , loqd irt  tr , NULL , 

"SPV", NULL, NULL))  • -1  THEN 
BEGIN 

PRlNir  ’“,crll)| 

CONTINUE  ~qatnam«*| 

END; 

COnnENT  tri^  pacH  dafault  And  if  not  found 
than  Iri^  o«Kt  until  non#  ar«  found  than 
print  ’ and  try  aqain; 

naifa  ••  JF  NS  < t a*»pChan , 8)j 

COMMENT  qatt  nama  of  ffla  on  chan  — 0 
maans  in  nornal  format; 

CF ILE  f tampChan) ; 

COhHENT  channa I not  optnad  but  doaa 
naad  to  ha  raiaatad; 

DONE  "qatnama*; 

END; 

this  c <ve  did  not  want  to  open  a channel 
at  all  since  we  will  not  be  either  reading  or 
writing  the  .SAV  file  At  the  end  of  the  above 
code,  the  complete  filename  is  stored  in  STRING 
nam»  We  might  wish  to  run  the  program  with  the 
RUNPRG  routine.  GIJPN  and  GTJFNL  are  often 
used  tor  the  purpose  of  establishing  filenames 
even  though  they  are  not  to  be  opened  at  the 
icment.  However,  the  Sail  channel  does  need  to 
be  released  afterwards. 

Some  of  the  other  JSYS’s  which  have  been 
implemented  in  the  runtime  package  were  used 
in  this  program;  GJINF,  DIRST,  and  JFNS.  JFNS  in 
particular  is  very  useful  It  returns  a siring 
which  is  the  name  of  the  file  open  on  the 
channel.  You  might  need  this  name  to  record  or 
to  print  on  the  terminal  or  because  you  will  be 
Outputting  to  a new  version  of  the  input  file 
which  you  can’t  do  unless  you  know  its  name. 

These  and  a number  of  other  routines  are 
covered  in  Section  12  of  the  Sail  manual.  You 
should  probably  glance  through  and  see  what  is 
there.  Many  of  these  commands  correspond 
directly  to  utility  JSYS’s  available  in  TENEX  and 


will  be  difficult  to  use  if  you  are  no'  familiar  with 
the  JSYS’s  and  the  JSYS  manual. 


5 4 Input  from  a File 

In  this  section,  we  will  assume  that  you  have  a 
file  opened  for  reading  on  some  channel  and  are 
ready  to  it  out  Also  that  you  have  appropriately 
established  tne  end-ot-file  and  break  character 
variables  to  be  used  by  the  input  routines  and 
the  break  table  if  needed. 

Another  function  which  can  be  used  in 
conjunction  with  the  various  input  functions  is 
SETPL: 

SETPL  (chan#,  (lint#,  tpaqa#,  eto>#l 

This  allows  you  to  set  up  the  three  reference 
integer  variables  imt#,  paqa#,  and  to,/  to  be 
associated  with  the  channel  so  that  any  input 
function  on  the  channel  will  update  their  values. 
The  iina#  variable  is  incremented  each  time  a ’12 
(If)  IS  input  and  the  page#  variable  is  incremented 
(and  iina/  reset  to  0)  each  time  a ’lA  (formfeed) 
IS  input.  The  last  SOS  line  number  input  (if  any) 
will  be  in  the  loa#  variable  The  SETPL  should  be 
given  before  the  inputting  begins. 

The  major  input  function  for  text  is  INPUT. 

“raaulf  • INPUT  (chan#,  tabla#>{ 

where  you  give  as  arguments  the  channel 
number  and  the  break  table  number;  and  the 
resulting  input  string  is  returned.  This  is  very 
similar  to  SCAN. 

To  input  one  line  at  a time  from  a file  (where 
infiia  is  the  channel  number  and  iniiiaEoi  is  the 
end-of-file  variable); 

SE TBREBT (raadL inanCE TBREBk , M , NULL , ' i na " ) i 
00 

BEGIN 

STRING  llnai 

I man  INPUT ( ln( I la,  raadL ina) j 
...<proca<i  (ha  llna>... 

END 

UNTIL  InlllaEof; 

If  the  INPUT  function  sets  the  eof  variable  to 
TRUE  then  either  the  end-of-file  was 
encountered  or  there  was  a read  error  of  some 
sort. 
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If  the  INPUT  terminated  because  a breaK 
character  was  read  then  the  break  character  will 
be  in  the  brchar  variable.  If  brchar=0  then  you 
have  to  look  at  the  eof  variable  also  to 
determine  what  happened:  If  eof^TRUE  then  that 
was  what  terminated  the  INPUT  but  if  eof-TAiSE 
and  brchar^^O  then  the  INPUT  was  terminated  by 
reaching  the  maximum  count  per  input  that  was 
specified  for  ttie  channel. 

If  you  are  inputting  numbers  from  the  channel 
then 

rt.xIVar  . Rf  QLIN(chjn/l 
in»«q6'*Vir  » lNTIh(cHan#) 

whifh  are  liRe  PEALSCAN  and  INTSCAN  can  be 
u'-ed  The  brchar  established  tor  the  channel 
will  be  used  rather  than  needing  to  give  it  as  an 
argument  as  in  the  REALSCAN  and  INTSCAN. 

INPUT  IS  designed  for  files  of  text.  Several  other 
input  functions  are  available  for  other  sorts  of 
files 

Number  ••  UOROIN  (chan#) 

will  read  m a 36-bit  word  from  a binary  format 
file.  For  defails  see  the  manual. 

PRR^IN (chan#,  #loc,  count) 

IS  used  for  filling  arrays  with  data  from  binary 
format  files.  Count  IS  the  number  of  36-bit  words 
to  be  read  m from  the  file  They  are  placed  in 
consecutive  locations  starting  with  the  location 
specified  by  loc,  e g., 

INTEGER  RRRPV  numbt  IlixiJx); 

PRRYlNtdataT  i lo  ,nuixtot  111  ,maK)  •, 

ARRYIN  can  only  be  used  for  INTEGER  and  REAL 
arrays  (not  STRING  arrays). 

6. A 1 Aciditional  TENEX  Sail  Input  Routines 

Two  extra  input  routines  which  are  quite  fast 
have  been  added  to  TENEX  Sail  to  utilize  the 
available  input  JSYS’s. 

char  CHRP  IN  (chan#) 

inputs  a single  character  which  can  be  assigned 
to  an  integer  variable.  It  the  file  is  at  the  end 
then  CHARIN  returns  0. 


"ra»u  M " ► 

SINl  (chan#,  maxtanqth,  br  aatf -Chjr  ac  t #r  ) 

does  a very  fast  input  of  a string  which  is 
terminated  by  either  reading  «i«<iini)th  characters 
or  encountering  the  broar -ct>ar*ct«r.  Note  that 
the  broai -char»ct«r  here  IS  not  a reference 
integer  where  the  break  character  is  to  be 
returneo;  rather  it  actually  is  the  break 
character  to  be  used  like  the  "break-characters" 
established  in  a break  table  except  that  only  one 
character  can  be  specified.  If  the  SINl  terminated 
for  reaching  ma.itnqth  then  !SKIP!  - -1  else  ISKIP! 
will  contain  the  break  character. 

TENEX  Sail  also  offers  random  I/O  which  is  not 
available  in  TOPS- 10  Sail.  A file  bytepointer  is 
rr.ainlaineo  for  each  file  and  is  initialized  to  point 
at  the  beginning  of  the  file  which  is  byte  0.  It 
subseouehtly  iriOves  through  the  file  always 
pointihg  to  the  character  where  the  next  read  or 
write  will  begin.  In  fact  the  same  file  may  be 
read  and  written  at  the  same  time  (assuming  it 
has  been  opened  in  the  appropriate  way).  If  the 
pointer  could  only  move  in  this  way  then  only 
sequential  I/O  would  be  available  However,  you 
can  reset  the  pointer  to  any  random  position  in 
the  file  and  begin  the  read/wnte  at  that  point 
which  IS  called  random  I/O. 

Charptr  RCHPTR  (cban#) 

returns  the  current  position  of  the  character 
pointer.  This  is  given  as  an  integer  representing 
the  number  of  characters  (bytes)  from  the  start 
of  the  file  which  is  byte  0.  You  can  reset  the 
pointer  by 

SCHPTR  Icban#,  nauptr) 

It  ntupir  IS  given  as  -1  then  the  pointer  will  be 
set  to  the  end-of-file. 

There  are  many  uses  for  random  I/O.  For 
example,  you  can  store  the  help  text  for  a 
program  in  a separate  file  and  keep  track  of  the 
bytepointer  to  the  start  of  each  individual 
message.  Then  wh^n  you  want  to  print  Out  one 
of  the  messages,  you  can  set  the  file  pointer  to 
the  start  of  the  appropriate  message  and  print  it 
Out. 

RWOPTR  AND  SWDPTR  are  also  available  for 
random  I/O  with  words  (36-bit  bytes)  as  the 
primary  unit  rather  than  characters  (7-bit  bytes). 
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6.5  Output  to  a File 

The  CPRINT  function  is  used  for  outputting  to 
text  files. 

CPRINT  (eh*n#,  irql,  »r92,  irqN) 

CPRINT  is  just  like  PRINT  except  that  the  channel 
must  be  given  as  the  first  argument. 

POP  1-1  STEP  1 until  «a<Uork*rt  DO 
CPRINT (out M )•,  namoltif  " 

( I ] ,cr I f ) } 

Each  subsequent  argument  is  converted  to  a 
string  if  necessary  and  printed  out  to  the 
channel. 

UOROOUT (chan# , numbar) 

writes  a single  36-bit  word  to  the  channel. 

PRRYOUT (chan#,  aloe,  count) 

writes  out  an  array  by  outputting  count  number 
of  consecutive  words  starting  at  location  loc. 

REPL  RRRflY  raaulta  UiiMxJ| 

RRRYOUT  (ratu  I tF  I la,raau  I ta  (1)  ,Mx)  | 

TENEX  Sail  also  has  the  routine: 

CHRROUTtchan#,  char) 

which  outputs  a single  character  to  the  channel. 

The  OUT  function  is  generally  obsolete  now  that 
CPRINT  is  available. 
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SECTION  6 
Records 

Records  are  the  newest  data  structure  in  Sail. 
They  take  us  beyond  the  basic  part  of  the 
languaf.e,  but  we  describe  them  here  in  the  hope 
that  f/iey  will  be  very  useful  to  users  of  the 
language  Sail  records  are  similar  to  those  in 
Al  GOL  W (see  Appendix  A for  the  differences). 
Some  other  languages  that  contain  record-like 
‘.tructures  are  Simula  and  PASCAL. 

Records  can  be  extremely  useful  in  setting  up 
complicated  data  structures.  They  allow  the  Sail 
programmer:  1)  a means  of  program  controlled 
storage  allocation,  and  2)  a siiriple  method  of 
referring  to  bundles  of  information.  (Loc*lion(x) 
and  memorgix),  which  are  not  discussed  here  and 
srioold  be  thought  of  as  liberation  from  Sail, 
allow  one  to  deal  with  addresses  of  things.) 

6 1 Declaring  and  Creating  Records 

A record  is  rather  like  an  array  that  can  have 
objects  of  different  syntactic  types.  Usually  the 
record  represents  different  kinds  of  information 
about  one  Object.  For  example,  we  can  have  a 
class  of  records  called  p»rion  that  contains 
records  with  information  about  people  for  an 
accounting  program.  Thus,  we  might  want  to 
keep:  the  person's  name,  address,  account 

number,  monetary  balance  We  could  declare  a 
record  class  thus: 

•rtCOirO'CLOSS  pprion  (STRING  n*i»»,  taarttf, 
INTECLR  account; 

REAL  balanct) 

This  occurs  at  declaration  level,  and  the 
identifier  porton  IS  available  within  the  current 
block  --  just  like  any  other  identifier. 

RECORDfCLASS  declarations  do  not  actually 
reserve  any  storage  space.  Instead  they  define 
a pattern  or  template  for  the  class,  showing  what 
fields  the  pattern  has  In  the  above,  nam,  aodraia, 
account  and  baianct  are  all  fields  of  the 
RECORD'CLASS  par  .on. 

To  create  a record  (e  g.,  when  you  get  the  data 
on  an  actual  person)  you  need  to  call  the 
NEWtRECORD  procedure,  which  takes  as  its 
argument  the  RECORDfCLASS.  Thus, 


rp  NEU'RECORO  (ptrson); 

creates  a person,  with  all  fields  initially  0 (or 
NULL  for  strings,  etc).  Records  are  created 
dynamically  by  the  program  and  are  garbage 
collected  when  there  is  no  longer  a way  to 
access  them. 

When  a record  is  created,  NEWIRECORD  returns  a 
pointer  to  the  new  record.  This  pointer  is 
typically  stored  in  a RECORDIPQINTER 
RECORDIPQlNTERs  are  variables  which  must  be 
declared.  The  RECORDtPOINTER  rp  was  used 
above.  There  is  a very  important  distinction  to 
be  made  between  a RECORDfPOINTER  and  a 
RECORD.  A RECORD  is  a block  of  variables  called 
fields,  and  a RECORDIPOINTER  is  an  entity  that 
points  to  some  RECORD  (hence  can  be  thought  of 
as  the  "name"  or  "address"  of  a RECORD).  A 
RECORD  has  fields,  but  a RECORDIPOINTER  does 
not,  although  its  associated  RECORD  may  have 
fields.  The  following  is  a complete  program  that 
declares  a RECORDfCLASS,  declares  a 

RECORDIPOINTER,  and  creates  a record  in  the 
RECORDfCLASS  with  the  pointer  to  the  new 
record  stored  in  the  RECORDIPOINTER. 

BEGIN 

RCCORO'CLRSS  p«r»on  (STRING  namt . addrpss ; 

INTEGER  account; 

RCPL  balancfl}} 

RECORO'POINTER  (parson)  rp; 

COnriENT  pro9ram  starts  bars.; 

rp  NCU'RECORO  (parson); 

END; 


RECORDIPOINTERs  are  usually  associated  with 
particular  record  class(es).  Notice  that  in  the 
above  program  the  declaration  of 
RECORDIPOINTER  mentions  the  class  p.r.on: 

RECORO'POINTER  (person)  rp; 

This  means  that  the  compiler  will  do  type 
checking  and  make  sure  that  only  pointers  to 
records  of  class  p.r.on  will  be  stored  into  rp.  A 
RECORDIPOINTER  can  be  of  several  classes,  as  in: 

RECORO'POINTER  (person,  university)  rpg 

assuming  that  we  had  a RECORDfCLASS 

uni  vtrs  1 

RECORDIPOINTERs  can  be  of  any  class  if  we  say: 
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RECORD'POINTER  (ANYICLASS)  rp; 

but  declaring  the  class(es)  o(  record  pointers 
gives  compilation  time  checking  of  record  class 
agreement.  This  becomes  an  advantage  when 
you  have  several  classes,  since  the  compiler  will 
complain  about  many  of  the  simple  mistakes  you 
can  make  by  mis-assigning  record  pointers. 


6.2  Accessing  Fields  of  Records 

The  fields  of  records  can  be  read/written  just 
like  the  elements  of  arrays.  Developing  the 
above  program  a bit  more,  suppose  we  have 
created  a new  record  of  class  p»rton,  and  stored 
the  pointer  to  that  record  in  rp.  Then,  we  can 
give  the  "person”  a name,  address,  etc.,  with  the 
following  statements. 

p»r ton : (rp)  ► "John  0o«”| 

por  ion : Jddrots  (r  p]  *■  "101  CJSt  tPntinq  Slrtot*) 
p#r»on:  Pccounl  (rp)  U; 
porson: I Anc*  (rp)  » 3008.67} 

and  we  could  write  these  fields  out  with  the 
statement: 


6.3  Linking  Records  Together 

Notice,  in  the  above  example,  that  as  we  create 

the  persons,  we  have  to  store  the  pointers  to 

the  records  somewhere  or  else  they  will  become 

"missing  persons".  One  way  to  do  this  would  be 

to  use  an  array  of  record  pointers,  allocating  as 

many  pointers  as  we  expect  to  have  people.  If 

the  number  of  people  is  not  known  in  advance  i 

then  the  more  customary  approach  is  to  link  the 

records  together,  which  is  done  by  using 

additional  fields  in  the  records. 

Suppose  we  upgrade  the  above  example  to  the 
following; 

RECORD'ClftSS  ptrton  (STRING  nam«,  addrass; 

INTEGER  account; 

REPL  balanct; 

REC0R0'P0INTER(PNY'CLPS3>  na»t); 

Notice  now  that  there  is  a RECORDIPOINTER  field 
in  the  template.  This  may  be  used  to  keep  a 
pointer  to  the  next  person.  The  header  to  the 
entire  list  o1  persons  will  be  kept  in  a single 
RECORDIPOINTER. 


PRINT  it  ”,  p«rton:na»«(rp) , cr  I ( , 

"Pddrtsa  li  ",  ptrson:addrass(rp) , crif, 
"Pccount  1%  ",  parion:account (rp)  , cril, 
"Balanct  it  ”,  pt'‘ion:balanct(rp) , crif); 

The  syntax  for  fields  has  the  following  features: 

1)  The  fields  are  available  within 

the  lexical  scope  where  the 

RECORDICLASS  was  declared,  and  follow 

ALGOL  block  structure. 

2)  The  fields  in  different  classes 

may  have  the  same  name,  e g.,  p*r«ni :na«i« 
and  chi  idinpmp. 


Thus,  the  following  program  would  create 
persons  dynamically  and  put  them  into  a "linked 
list”  with  the  newest  at  the  head  of  the  list.  This 
technique  allows  you  to  write  programs  that  are 
not  restricted  to  some  fixed  maximum  number  of 
persons,  but  instead  allocate  the  memory  space 
necessary  lor  a new  person  when  you  need  it. 


eECIN 

RECORO'CLPSS  ptrson  (STRING  n«m«,  addrpts; 
INTEGER  account;  REPL  balanca; 
RECORO'POINTER(PNY)CLPSS)  noKt); 

RECORO'POINTER  (PNYICLPSS)  haadar; 


3)  The  syntax  is  rather  like  that  for 
arrays  --  using  brackets  to  surround  the 
record  pointer  in  the  same  way  brackets 
are  used  for  the  array  index. 

4)  The  fields  can  be  read  or  written 
into,  also  like  array  locations. 


5)  It  is  necessary  to  write 

c latt I < I*  Id Ipo Inter]  --  i.e.,  you  have  to 
include  the  name  of  the  class  (her# 
aarien)  With  a before  the  name  of  the 
field. 


I 


WHILE  TRUE  DO 
BEGIN 

STRING  ft; 

RECORO'POINTER  (PNYICLPSS)  tamp; 

PRINT("Nama  of  noKt  parson,  CR  if  dona:"); 
ir  NOT  LENGTH (t  •-  INCHUD  THEN  DONE; 

COnnENT  put  nau  parson  at  haad  of  list; 
tamp  NEU'RECORO(parson)  t 
COnnENT  maka  a nau  racord; 
paraontnaxt  (tamp)  •>  haadar; 

COnnCNT  tha  old  haad  bacomat  tha  sacond; 
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COnniNT  tH«  n«w  record  btcon>«i  tht  h««d| 

CO^n^NT  now  fill  inforiMttOn  fitldl; 
p»r son : nam«  1 1 Ainp)  •-  i; 

COnniNT  now  wo  can  fill  addrots,  account, 
ba I anca  i * wa  wan t . . . ; 

END; 

END; 


A very  powerful  feature  of  record  structures  is 
the  ability  to  have  different  sets  of  pointers. 
For  example,  there  might  be  both  forward  and 
backward  links  (in  the  above,  we  used  a forward 
link).  Structures  Such  as  binary  trees,  sparse 
matrices,  deques,  priority  queues,  and  so  on  are 
natural  applications  of  records,  but  it  will  take  a 
Mtle  study  of  the  structures  in  order  to 
understand  how  to  build  them,  and  what  they  are 
good  lor. 

Be  warned  about  the  difference  between 
records,  record  pointers,  record  classes,  and  the 
fields  of  records:  they  are  all  distinct  things,  and 
you  can  get  in  trouble  if  you  forget  it.  Perhaps 
a simple  example  will  show  you  what  is  meant; 

begin 

RECORO'CinSS  pair  (INTEGER  I,  j)( 

RECORO'POINTER  (pair)  a,  b,  c,  d; 

a > NEU'RECORO  (pair)) 
pa  tr  : I [al  ••  1 ; 
pa  ir : j (a)  ••  2; 
d A ; 

b - NEU'RECQNO  (pair) ; 
pa  ir : i (b1  ••  1 , 
pair:  j (b]  •‘7', 
c * NEU'RECORO  (pair); 
pa  ir  : I (c)  1 ; 

pa  ir : J (c)  * 3; 

IE  a ■ b then  PR]NT(  * A • B ” ) ; 
pair:)  (d)  » 3; 

IF  a > c ^HEN  PRINK  *■  fl  . C " ); 

IF  c ■ d Then  prink  " C ■ 0 “ ); 

ir  a « d then  PRINT!  ” A - 0 * ) ; 

PRINT  ( ' (A  I : pair: t la) , ",  J: ", 

pa  ir : J (al , " ) " ) ; 

PRINK  * (B  li",  pain  i Ibl , J:", 

pa  ir : J (b) , ") " ) ; 

PRINK  - (C  Ii",  pain  i Id,  ",  Ji". 

pa  ir : J Ed  , ") " ) ; 

PRINK  * (0  Ii".  paint  (dl,  ",  Ji", 
pa  ir  I J Idl , ") ” ) ; 

ENO) 

will  print; 


R • D (R  III  J:3l  (B  1:1,  J;2) 

(C  III,  Ji3)  (D  111,  Ji3) 

Note  that  two  RECORDtPOINTERs  are  only  equal  if 
they  point  to  the  same  record  (regardless  of 
whether  the  fields  of  the  records  that  they  point 
to  are  equal).  At  the  end  of  executing  the 
previous  example,  there  are  3 distinct  records, 
one  pointed  to  by  RECORDtPOINTER  b,  one 
pointed  to  by  RECORDtPOINTER  c,  and  one 
pointed  to  by  RECORDtPOINTERs  a and  d.  When 
the  line  that  reads:  painj  Id)  ► 3j  is  executed, 
the  j-field  of  the  record  pointed  at  by 
RECORDtPOINTER  d is  changed  to  3,  not  the  j-field 
of  d (RECORDtPOINTERs  have  no  fields).  Since 
that  IS  the  same  record  as  the  one  pointed  to  by 
RECORDtPOINTER  a,  when  we  print  painj  lal,  we 
get  the  value  3,  not  2. 

Records  can  also  help  your  programs  to  be  more 
readaole,  by  using  a record  as  a means  of 
returning  a collection  of  values  from  a procedure 
(no  Sail  procedure  can  return  more  than  one 
value).  If  you  wish  to  return  a RECORDtPOINTER, 
then  the  procedure  declaration  must  indicate  this 
as  an  additional  type-qualifier  on  the  procedure 
declaration,  for  example: 

RECORDiPOINTER  (ptrton)  PROCEDURE  maxBa I anca; 

BEGIN 

RECORO'POINTER  (per»on)  tempH*ader , 

currtntflaKPtrton; 

REAL  currantMax; 

tampHaadar  haadar; 

currantflax  paraon:  ba  I anca  E tampHaadar] ; 

currantUaxParion  tampHaadar; 

UHILE  tampHaadar  partonmaxt  (tampHaadar)  00 

IF  par«on:ba lanca  (tampHaadar)  > currantflax  THEN 
BEGIN 

currantHax  » paraon: ba ianca  (tampHaadar); 
currantNaxParaon  tampHaadar; 

END; 

RETURN  (currantFlaxParaon) ; 

ENO; 

This  procedure  goes  through  the  linked  list  of 
records  and  finds  the  person  with  the  highest 
balance.  It  then  returns  a record  pointer  to  the 
record  of  that  person.  Thus,  through  the  single 
RETURN  statement  allowed,  you  get  both  the 
name  of  the  person  and  the  balance. 

RECORDtPOINTERs  can  also  be  used  as  arguments 
to  procedures;  they  are  by  default  VALUE 
parameters  when  used.  Consider  the  following 
quite  complicated  example; 

RCCORO'CinSS  pnt  (REAL  x,ij,i); 

RECORDIPOINTER  (pnt)  PROCEDURE  ■ndpoinl 

(RECORO'POINTER  (pnt)  p,b)| 
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BEGIN 

RECORDiPOINTER  (pnt)  rilval| 
rctval  - NEUIRECORO  (pnl); 

pnf:ic  Irtlval)  *■  (pnllx  [a]  4 pn1;K  lb]  ) / 2\ 

pnt:g  [ralval]  *■  (pnt:y  (al  4 pntt^  (bl ) / 2| 

pnt!Z  [ratvatl  4 (pnliz  la)  4 pnliz  Ib} ) / 2; 

RETURN)  ralval  )| 

END; 


p •-  in  >dpo  ml  ( q,  r ) ; 

While  this  procedure  may  appear  a bit  clumsy,  it 
makes  it  easy  to  talk  about  such  things  as  pnis 
later,  using  simply  a record  pointer  to  represent 
each  pnl.  Another  common  method  for 
"returning"  more  than  one  thing  from  a 
procedure  is  to  use  REFERENCE  parameters,  as  in 
the  following  example: 

PROCEDURE  aiidpainl  (REFERENCE  RERL  rK,ry,rij 
RERL  ax,ay,az,bx,by,bz)| 

BEGIN 

rx  4 (av  4 bx)  / 2; 
ry  4 (ay  4 by)  / 2; 
rz  4 (az  4 bz)  / 2i 
END| 

fllDPOINT)  px,  py,  pz,  qx,  qy,  qz,  rx,  ry,  rz,  >| 

Here  the  code  for  the  procedure  looks  quite 
simple,  but  there  are  so  many  arguments  to  it 
that  you  can  easily  get  lost  in  the  main  code. 
Much  of  the  confusion  comes  about  because 
procedures  simply  cannot  return  more  than  one 
value,  and  the  record  structure  allows  you  to 
return  the  name  of  a bundle  of  Information. 
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SECTION  7 

Conditional  Compilation 


Conditional  compilation  is  ava  lable  so  that  the 
same  source  file  can  be  used  to  compile  slightly 
different  versions  of  the  program  for  r^iflerent 
purposes.  Conditional  compilation  is  ha  idled  by 
the  scanner  in  a way  similar  to  the  handling  of 
macros  The  text  of  the  source  file  is 
manipulated  before  it  is  compiled  The  format  is 

IFCR  boolean  THENJ  code  ELSEC  code  ENOC 

This  construction  is  not  a statement  or  an 
expression.  It  is  not  followed  by  a semi-colon 
but  just  appears  at  any  point  in  your  program. 
The  ELSEC  is  optional  The  ENDC  must  be 

included  to  mark  the  end  but  no  begin  is  used. 
The  code  which  follows  the  THEIMC  (and  ELSEC  if 
used)  can  be  any  valid  Sail  syntax  or  fragment  of 
syntax.  As  with  macros,  the  scanner  is  simply 
manipulating  text  and  does  not  check  that  the 
text  IS  valid  syntax 

The  boolean  must  be  one  which  has  a value  at 
compile  time.  This  means  it  cannot  be  any  value 
computed  by  your  program.  Usually,  the  boolean 
will  be  DEEINE’d  by  a macro  For  example: 

INE  • <TRUE>; 

irCR  t I Vt'‘ 1 1 of>  THCNC  max  •- 

ELSEC  max  » leOatolal;  ENDC 

where  every  difference  in  the  program  between 
the  small  and  large  versions  is  handled  with  a 
similar  IFCR  THENC.  ENDC  construction.  For  this 
construction,  the  scanner  checks  the  value  of  the 
boolean;  and  if  it  is  TRUE,  the  text  following 
THENC  is  inserted  in  the  source  being  sent  to  the 
inner  compiler--other wise  the  text  is  simply 
thrown  away  and  the  code  following  the  ELSEC 
(if  any)  IS  used.  Here  the  code  used  for  the 
above  will  be  max  > ie*ioi«i|,  and  if  you  edit  the 
program  and  instead 

DEFINE  inal  IVcri  ion  « <ERlSE>; 

the  result  will  be  mtt  iee«toi*i;. 

The  code  following  the  THENC  and  ELSEC  will  be 
taken  exactly  as  is  so  that  statements  which 
need  final  semi-colons  should  have  them.  The 
above  format  of  staioaoni  | ELSEC  is  correct. 


If  this  feature  were  not  available  then  the 
following  would  have  to  be  used: 

BOOLLRN  tmj I I V«r s « on { 

• mjIlVortion  •>  TRUE; 

ir  imallVortion  THEN  max  w 10«total 
ELSE  max  ••  168*  to  ta  1 1 


so  that  a conditional  would  actually  appear  in 
your  program 

Some  typical  uses  of  conditional  compilation  are; 

1)  Insertion  of  debugging  or  testing 
code  for  experimental  versions  of  a 
program  and  then  removal  for  the  final 
version.  Note  that  the  code  will  still  be 
in  your  source  file  and  can  be  turned 
back  on  (recompilation  is  of  course 
required)  at  any  time  that  you  again  need 
to  debug.  When  you  do  not  turn  on 
debugging,  the  code  completely 
disappears  from  your  program  but  not 
from  your  source  file 

2)  Maintainence  of  a single  source 
file  for  a program  which  is  to  be 
exported  to  several  sites  with  minor 
differences. 

OEEINE  iummx  « <TRUE>, 
ifti  « «EPLSE>; 

IFCR  iumex  THENC  docitr  •-  "OOC;  ENOC 

IFCR  iftt  TMENC  docdfr  ► "OOCUnENTflTION";  ENOC 

where  only  one  Site  is  set  to  TRUE  for 
each  compilation. 

3)  "Commenting  out"  large  portions 
Of  the  program.  Sometimes  you  need  to 
temporarily  remove  a large  section  of  the 
program.  You  can  insert  the  word 
COMMENT  preceding  every  statement  to 
be  removed  but  this  is  a lot  of  extra 
work.  A better  way  is  to  use: 

IFCR  false  TMENC 

<dll  th«  codt  lo  bt  "r«mov«d*> 

ENOC 
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SECTION  8 

Systems  Building  in  Sail 


Many  new  Sail  u'.ers  will  find  their  first  Sail 
project  involved  with  adding  to  an  already- 
existing  system  of  large  size  that  has  been 
worked  on  by  many  people  over  a period  of 
years.  These  systems  include  the  speech 
recognition  programs  at  Carnegie  Mellon,  the 
hand-eye  software  at  Stanford  Al,  large  CAI 
systems  at  Stanford  IMSSS,  and  various  medical 
programs  at  SUMEX  and  NIH.  This  section  does 
not  attempt  to  deal  with  these  individual  systems 
in  any  detail,  but  instead  tries  to  describe  some 
of  the  features  of  Sail  that  are  frequently  used 
in  systems  building,  and  are  common  to  all  these 
systems  The  exact  documentation  of  these 
features  is  given  elsewhere;  this  is  intended  to 
be  a guide  to  those  features. 

The  Sail  language  itself  is  procedural,  and  this 
means  that  programs  can  be  broken  down  into 
components  that  represent  conceptual  blocks 
comprising  the  system.  The  block  structuring  of 
ALGOL  also  allows  for  local  variables,  which 
should  be  used  wherever  possible.  The  first  rule 
of  systems  building  is:  break  the  system  down 
into  modules  corresponding  to  conceptual  units. 
This  IS  partly  a question  of  the  design  of  the 
system--indeed,  some  systems  by  their  very 
design  philosophy  will  defy  modularity  to  a 
certain  extent.  As  a theory  about  the 
representation  of  knowledge  in  computer 
programs,  this  may  be  necessary;  but  programs 
should,  most  people  would  agree,  be  as  modular 
"as  possible". 

Once  modularized,  most  of  the  parts  of  the 
system  can  be  separate  files,  and  we  shall  show 
below  how  this  is  possible.  Of  course,  the 
modules  will  have  to  communicate  together,  and 
may  have  to  share  common  data  (global  arrays, 
flags,  etc.).  Also,  since  the  modules  will  be 
sharing  the  same  core  image  (or  job),  there  are 
certain  Sail  and  timesharing  system  resources 
that  will  have  to  be  commonly  shared.  The  rules 
to  follow  here  are: 

1)  Make  the  various  modules  of  a 
system  as  independent  and  separate  as 
design  philosophy  allows. 


2)  Code  them  in  a similar  "style"  for 
readability  among  programmers 

3)  Make  the  points  of  interface  and 
communication  between  the  programs  as 
clear  and  explicit  as  possible. 

A)  Clear  up  questions  about  which 
modules  govern  system  resources  (Sail 
and  the  timesharing  system),  such  as 
files,  terminals,  etc.  so  that  they  are  not 
competing  with  each  other  for  these 
resources. 

8.1  The  Load  Module 

The  most  effective  separation  of  modules  is 
achieved  through  separate  compilations.  This  is 
done  by  having  two  or  more  separate  source 
files,  which  are  compiled  separately  and  then 
loaded  together.  Consider  the  following  design 
for  an  Al  system  QWERT.  QWERT  will  contain 
three  modules:  a scanner  module  XSCAN,  a 
parser  module  PARSE,  and  a main  program 
QWERT.  W>  give  below  the  three  files  for 
QWERT. 

First,  the  QWERT  program,  contained  in  file 
QWERT.SAI: 

BECIN-QUtRT- 

EXTERNRL  STRING  PROCEDURE  XSCRN (STRING  S)  j 
REOUIRE  ’XSCRN-  lORD'HOOULE; 

external  string  procedure  PARSE (STRING  S) ; 

REQUIRE  "PARSE"  LOAO'nODULE) 

WHILE  TRUE  00 
BEGIN 

PRINT ("»", PARSE (XSCAN ( INCHUL ) ) ) ; 

END; 

END'QWERT": 

Notice  two  features  about  QWERT.SAI: 

1)  There  are  two  EXTERNAL 
declarations.  An  EXTERNAL  declaration 
says  that  some  identifier  (procedure  or 
variable)  Is  to  be  used  in  the  current 
program,  but  it  will  be  found  somewhere 
else.  The  EXTERNAL  causes  the  compiler 
to  permit  the  use  of  the  identifier,  as 
requested,  and  then  to  issue  a request 
for  a global  fixup  to  the  LOADER 
program. 
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7)  Secondly,  there  are  two  REQUIRE 
LOADtMODULE  statements  in  the 
program.  A load  module  is  a file  that  is 
loaded  by  the  loader,  presumably  the 
output  of  some  compiler  or  assembler. 
These  REQUIRE  statements  cause  the 
compiler  to  request  that  the  loader  load 
modules  XSCAfJ.REL  and  PARSE. REL  when 
we  load  MAIN.REL,  This  will  hopefully 
satisfy  the  global  requests:  i.e.,  the 

loader  will  find  the  two  procedures  in  the 
two  mentioned  files,  and  link  the 
programs  all  together  into  one  "system". 

Second,  the  code  for  modules  XSCAN  and  PARSE; 

ENTHV  XSCBN; 

BEGIN 

INTERNRl  string  PROCEDURE  XSCRNISTRINC  S)  j 
BEGIN 

cod*  lor  XSCRN  

RETURN  (rotuMinq  ftrinqli 
ENOi 

END; 

and  now  PARSE. SAI: 


LINKIO)  that  are  available  on  the  system. 

In  particular,  there  is  no  way  to  associate 
an  external  symbol  with  a particular 
LOADtMODULE. 

2)  The  names  of  identifiers  are 
limited  to  SIX  characters,  and  the 
character  set  permissible  is  slightly  less 
than  might  be  expected  The  symbol 

IS,  for  example,  mapped  into  m global 
symbol  requests. 

3)  The  "semantics"  of  a symbol 
(eg.,  whether  the  symbol  names  an 
integer  or  a string  procedure)  is  in  no 
way  checked  during  loading. 

Initialization  routines  in  a LOADtMODULE  can  be 
performed  automatically  by  including  a REQUIRE 
INITIALIZATION  procedure.  For  example, 
suppose  that  INIT  is  a simple  parameterless, 
valueless  procedure  that  does  the  initialization 
for  a given  module: 

SlffPLE  PROCEDURE  INITj 
BEGIN 

...initialization  cod*. . . 

twO: 


I 


ENTRy  PARSE  1 
BEGIN 

INTERNAL  STRING  PROCEDURE  PARSE (STRING  SI) 

BEGIN 

....cod*  (or  PARSE.... 

RE  TURN (r *su I 1 t nq  .Irinq); 

ENOj 

ENDj 

Both  of  these  modules  begin  with  an  ENTRY 
declaration  This  has  the  effect  of  saying  that 
the  program  to  be  compiled  is  not  a "main" 
program  (there  can  be  Only  one  main  program  in 
a core  image),  and  also  says  that  PARSE  is  to  be 
found  as  an  INTERNAL  within  this  file.  The  list  of 
tokens  after  the  ENTRY  construction  is  mainly 
used  for  LIBRARYs  rather  than  LOADtMODULEs, 
and  we  do  not  discuss  the  difference  here,  since 
LIBRARYs  are  not  much  used  in  system  building 
due  to  the  difficulty  in  constructing  them. 

A few  important  remarks  about  LOAOtMODULES: 

1)  The  use  of  LOADIMODULES 
depends  on  the  loaders  (LOADER  and 


REQUIRE  INIT  INITIALIZATION, 

Will  run  INIT  prior  to  the  outer  block  of  the  mam 
program.  It  is  difficult  to  control  the  order  in 
which  initializations  are  done,  so  it  is  advisable 
to  make  initializations  that  do  not  conflict  with 
each  other. 


8.2  Source  Files 

In  addition  to  the  ability  to  compile  programs 
separately.  Sail  allows  a single  compilation  to  be 
made  by  inserting  entire  files  into  the  scan 
stream  during  compilation.  The  construction: 

REQUIRE  "FILENn.SRr  SOURCE 'E ILE ; 

inserts  the  text  of  file  FILENM.SAI  into  the  stream 
of  characters  being  scanned--having  the  same 
effect  that  would  be  obtained  by  copying  all  of 
FILENM.SAI  into  the  current  file. 

One  pedestrian  use  of  this  is  to  divide  a file  into 
smaller  files  (or  easier  editing.  While  this  can  be 
convenient,  it  can  also  unnecessarily  fragment  a 
program  into  little  pieces  without  purpose. 


46 


SAIL  TUTORIAL 


Systems  Building  in  Sail 


There  are,  however,  some  real  purposes  of  the 
SOURCFiriLF  construction  in  systems  building. 
One  use  is  to  include  code  that  is  needed  in 
several  places  into  one  file,  then  "REOUIRE"  that 
file  in  the  places  tnat  it  is  needed  Macros  are  a 
common  example  For  example,  a tile  of  global 
definitions  might  be  put  into  a tile  MACROS. SAI: 

RfQUIRE  ■->«>•  Of  I iniTfRSi 
OEFIHE  ReRBrsirr .<100>, 

NUnPfROf SIUOEHTS.<?00., 

F iifNnne.<"f  a.DRT->j 

A common  use  of  source  files  is  to  provide  a 
SOURCEIFILF  that  links  to  a load  module:  the 
source  file  contains  the  EXTERNAL  declarations 
for  the  procedures  (and  data)  to  be  found  in  a 
module,  and  also  requires  tnat  file  as  a load 
module  Such  a tile  is  sometimes  called  a 
"header'  file.  Consider  the  file  XSCAN.HDR  for 
the  above  XSCAN  load  module; 

FKTfRNBL  string  PROCfOURE  XSC«N(STRINC  S); 
RfQUIRE  "XSCRN-  LORO'ftOOULEi 

The  use  of  header  files  ameliorates  some  of  the 
defciencies  of  the  loader:  the  header  file  can, 
for  example,  be  carefully  designed  to  contain  the 
declarations  of  the  EXTERNAL  procedures  and 
data,  reducing  the  likelihood  of  an  error  caused 
by  misdeclaration.  Remember,  if  you  declare: 

INTERNRL  STRING  PROCEDURE  XSCRNISTRING  Sli 
BEGIN  END; 

•'1  one  file  and 

EXTERNOL  integer  procedure  XSCfiNISTRINC  S)j 

in  another,  the  correct  linkages  will  not  be  made, 
and  the  program  may  crash  quite  strangely. 


8 3 Macros  and  Conditional  Compilation 

Macros,  especially  those  contained  in  global 
macro  files,  can  assist  in  system  building. 
Parameters,  file  names,  and  the  like  can  be 
"macroized". 

Conditional  compilation  also  assists  in  systems 
building  by  allowing  the  same  source  files  to  do 
different  things  depending  on  the  setting  of 
switches.  For  example,  suppose  a file  FILE  is 
being  used  for  both  a debugging  and  a 
"production"  version  of  the  same  module.  We 
can  include  a definition  of  the  form: 


DEFINE  DEBUGGING. <FRLSE>) 

COnflENT  fait*  if  not  dabuqqinq; 

and  then  use  it 

IFCR  OEBUCCING  THENC 

PRINTCNow  *1  PRDC  PR  ",J,CRLF)j  ENDC 

(See  Section  7 on  conditional  compilation  for 
more  details.)  In  the  above  example,  the  code  will 
define  the  switch  to  be  FALSE,  and  the  PRINT 
statement  will  not  be  compiled,  since  it  is  in  the 
FALSE  consequent  of  an  IFCR  ...THENC.  In  using 
switches,  it  IS  common  that  there  is  a default 
setting  that  one  generally  wants.  The  following 
conditional  compilation  checks  to  see  if 
DEBUGGING  has  already  been  defined  (or 
declared),  and  if  not,  defines  it  to  be  false.  Thus 
the  default  is  established. 

IFCR  NDT  OECLRRflTIDN(DEBUGGING)  THENC 
DEFINE  OEBUCCING.xFRLSExi  ENDC 

Then,  another  file,  inserted  prior  to  this  one,  sets 
the  compilation  mode  to  get  the  DEBUGGING 
version  if  needed. 

Macros  and  conditional  compilation  also  allow  a 
number  of  complex  compile-time  operations,  such 
as  building  tables.  These  are  beyond  our 
discussion  here,  except  to  nnfe  that  complex 
macros  are  often  used  (overused?)  in  systems 
building  with  Sail. 
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APPENDIX  A 

Sail  and  ALGOL  W Comparison 

There  are  many  variants  of  AlGOL.  This 
Appendix  will  cover  only  the  mam  differences 
between  Sail  and  ALGOL  W. 

The  following  are  differences  in  terminology: 

ncCOL  U Sail 


Psstqnmenl  operator 

► 

• « 

E * ponen t 1 a t 1 on  oparator 

T 

Not  aqual 

r or  NEQ 

< e 

lass  than  or  equal 

5 or  LEO 

>« 

Greater  than  or  aqual 

> or  GEQ 

REN 

DfviS'On  rematndtr  operator 

noo 

END. 

Prografr  and 

END 

Rf 3ULT 

Procedure  p.^rametar  type 

REFERENCE 

l tr  ( 1 ) j ) 

Subs  tr inqs  s tr  1 

1 1 for  j ) 

STRINC(t 

) S Strtnq  aaclaratfon* 

STRING  « 

a'-  r y (1  ) 

Orray  subscr ipt 

arry  til 

df  ry  ( i : 

:18>  Rrray  declaration 

arry 11:181 

The  following  are  not  available  in  Sail: 

000  SOUND  ENIlfS 

TPUNCfiTE  Truncation  d«f«ult  convernon. 

UPITE,  UPjTtON  Us«  PRINT  s1al«nenl  tor  both. 

RFQOON  Us«  INPUT,  RfPLlN,  INTIN. 

Bloc*  OoprossiOns 

Pr  oc#dur • oxpr «ss ions 

U&t  RETURN 
tn  pr  ocodurts . 

Othe'  differences  are: 

1)  Iteratioi  variables  and  Labels  must  be 

cieclart-d  in  Sail,  but  the  iteration  variable  is 
more  general  since  it  can  be  tested  after 
the  loop 

2)  STEP  UNTIL  cannot  be  left  Out  in  the  FOR- 

statement  in  Sail. 

3)  Sail  strings  do  not  have  length  declared  and 

are  not  filled  Out  with  blanks 

A)  EQU  not  » IS  used  for  Sail  strings 

4S 


5)  The  first  case  in  the  CASE  staterr:ent  in  Sail  is 

0 rather  than  1 as  in  ALGOL  W (Note  that 
Sail  also  has  CASE  expressions.) 

6)  <,  and  > will  not  work  for  alphabetizing 

Sail  strings  Ttiey  are  arithmetic  operators 
only. 

7)  ALGOL  W pa'^ameter  passing  conventions 

vary  slightly  from  Sail.  The  ALGOL  W 
RESULT  parameter  is  close  to  the  Sail 
REFERENCE  pai-ameter,  but  there  is  a 
difference,  in  that  the  Sail  REFERENCE 
pararr.eter  passes  an  address,  whereas  the 
Algol  W result  parameter  creates  a copy 
of  the  value  during  the  execution  of  the 
procedure 

8)  A forward  procedure  declaration  is 

needed  in  Sail  if  another  procedure  calls  an 
as  yel  undeclared  procedure.  Sail  is  a one- 
pass  compiler. 

9)  Sail  uses  SiVPlf  n-'  iCEDLIRE,  PROCEDURE, 

and  RECURSIVE  PROCEDURE  where  ALGOL 
has  only  PROCEDURE  (equivalent  to  Sail's 
RECURSIVE  PROCEDURE). 

10)  Scalar  variables  in  Sail  are  not  cleared  on 

block  entry  m non-RECURSIVE  procedures. 

11)  Outer  block  arrays  in  Sail  must  have 

constant  bounds. 

12)  The  RECORD  syntax  is  considerably 

different.  See  oelo* 


Sail  feature'  (C  impro'.ement' t not  in  ALGOL  W: 

a)  Better  string  facilities  with  more  flexibility. 

b)  More  corr.picte  RLCLTRD  ' tructures 

c)  Use  of  DONE  and  CONTINUE  statements  for 

easier  control  of  loops. 

d)  Assignment  expressions  for  more  compact 

code 

e)  Complete  I/O  facilities. 

f)  Easy  interlace  to  machine  instructions 
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The  following 

compares  Sail 

and  ALGOL  W 

REFERENCES 

records  in  several  important  aspects. 

Psp«c  t 

Sa  1 1 

ALGOL  M 

1. 

Reiser,  John  (ed).  Sail,  Memo  AIM-289, 
Stanford  Artificial  Intelligence  Laboratory, 

0«C i«r«t ion 

RECORDiCLOSS 

RECORD 

of  Cl  ass 

August  1976. 

Dec  larat ion  of 

RECORD'POINTER 

REFERENCE 

2. 

Frost,  Martin,  UUO  Manual  (Second  Edition), 

rocord  pointar 

Pointers  can  be 

pointers  must 

Stanford  Artificial  Intelligence  Laboratory 
Operating  Note  55.4,  July  1975. 

several  c I asses  or 

be  to  one 

RNY'CLnSS 

c lass 

3. 

Harvey,  Brian  (M  Frost,  ed  ),  Monitor  Command 

Manual,  Stanford  Artificial  Intelligence 

E'npty  racord 

Reserved  Mord 

Reserved  uord 

Laboratory  Operating  Note  54.5,  January 

NULL 'RECORD 

NULL 

1976. 

F 1 a 1 ds  of  racord 

4, 

Feldman,  J A.,  Low,  JA  , Swinehart,  D.C., 

Use  brackets 

Use  parens 

Taylor,  R.H.,  “Recent  Developments  in  Sail", 
AFIPS  FJCC  1972,  p 1193-1202. 

riust  use 

Don' t use 

CLASS:  before  the 

c 1 ass  name 

5. 

DECSYTEMIO  Assembly  Language  Handbook 

field  name 

before  f leid 

(3rd  Edition),  Digital  Equipment  Corporation, 

Maynard,  Massachusetts,  1973, 


6.  DECbu'STEMlO  Us«rt  Handbook  (2nd  Edition), 

Digital  Equipment  Corporation,  Maynard, 
Massachusetts,  1972. 

7.  Myer,  Theodore  and  Barnaby,  John,  TENEX 

EXECUTIVE  Manual  (revised  by  William 
Plummer),  Bolt,  Beranek  and  Newman, 
Cambridge,  Massachusetts,  1973 

8.  JSYS  Manual  (2nd  Revision),  Bolt,  Beranek  and 

Newman,  Cambridge,  Massachusetts,  1973. 
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GTJFNL  35 

connected  directory  36 
constants  3 
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